sdd-flow 1.0.0 → 1.2.5
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/README.md +23 -21
- package/bin/cli.js +74 -8
- package/package.json +32 -32
- package/templates/QUICKSTART.md +48 -28
- package/templates/agents/AGENTS.md +92 -92
- package/templates/agents/RULES.md +116 -116
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +21 -21
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +24 -24
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +23 -23
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +3 -3
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +3 -3
- package/templates/agents/harness/claude-code/commands/sdd-research.md +3 -3
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +3 -3
- package/templates/agents/harness/opencode/commands/sdd-implement.md +3 -3
- package/templates/agents/harness/opencode/commands/sdd-plan.md +3 -3
- package/templates/agents/harness/opencode/commands/sdd-research.md +3 -3
- package/templates/agents/harness/opencode/commands/sdd-validate.md +3 -3
- package/templates/agents/prompts/rpi-implement.md +46 -46
- package/templates/agents/prompts/rpi-plan.md +117 -117
- package/templates/agents/prompts/rpi-validate.md +96 -96
package/README.md
CHANGED
|
@@ -19,32 +19,43 @@ npm install -g sdd-flow
|
|
|
19
19
|
## Usage
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
sdd init
|
|
23
|
-
sdd
|
|
24
|
-
sdd
|
|
22
|
+
sdd init # Installs the workflow into the current project
|
|
23
|
+
sdd new <name> # Creates a spec folder with auto-numbering
|
|
24
|
+
sdd harness # Installs, switches, or removes the agent harness
|
|
25
|
+
sdd update # Updates prompts and rules, preserves project data
|
|
25
26
|
sdd --version
|
|
26
27
|
```
|
|
27
28
|
|
|
28
|
-
> Alias
|
|
29
|
+
> Alias available: use `sdd` or `sdd-cli` — both work.
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
---
|
|
31
32
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
33
|
+
## After `init`
|
|
34
|
+
|
|
35
|
+
Open a new session with your agent and instruct:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
"Read and follow agents/SETUP.md"
|
|
35
39
|
```
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
- **New project:** describe the project or provide a PRD — the agent generates PROJECT.md and skills
|
|
42
|
+
- **Existing project:** the agent scans the codebase automatically
|
|
43
|
+
|
|
44
|
+
Review the generated files and delete `agents/SETUP.md`.
|
|
45
|
+
|
|
46
|
+
---
|
|
38
47
|
|
|
39
|
-
|
|
48
|
+
## Add or switch harness after init
|
|
40
49
|
|
|
41
50
|
```bash
|
|
42
51
|
sdd harness
|
|
43
52
|
```
|
|
44
53
|
|
|
45
|
-
Installs, replaces, or removes the harness and slash commands at any time
|
|
54
|
+
Installs, replaces, or removes the harness and slash commands at any time.
|
|
55
|
+
|
|
56
|
+
---
|
|
46
57
|
|
|
47
|
-
|
|
58
|
+
## Update workflow (preserves your project data)
|
|
48
59
|
|
|
49
60
|
```bash
|
|
50
61
|
sdd update
|
|
@@ -54,15 +65,6 @@ Updates `AGENTS.md`, `RULES.md`, `QUICKSTART.md`, and all prompts. Your `PROJECT
|
|
|
54
65
|
|
|
55
66
|
---
|
|
56
67
|
|
|
57
|
-
## After `init`
|
|
58
|
-
|
|
59
|
-
1. Open a new session with your agent
|
|
60
|
-
2. Instruct: *"Read and follow `agents/SETUP.md`"*
|
|
61
|
-
3. Provide your PRD or describe the project
|
|
62
|
-
4. Review the generated files and delete `agents/SETUP.md`
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
68
|
## The RPI Cycle
|
|
67
69
|
|
|
68
70
|
Each feature goes through four isolated phases, each in its own agent session:
|
package/bin/cli.js
CHANGED
|
@@ -134,8 +134,9 @@ async function init() {
|
|
|
134
134
|
log(bold('Próximos passos:'));
|
|
135
135
|
log(` ${c.cyan}1.${c.reset} Abra uma sessão do seu agente no projeto`);
|
|
136
136
|
log(` ${c.cyan}2.${c.reset} Instrua: ${dim('"Leia e siga agents/SETUP.md"')}`);
|
|
137
|
-
log(`
|
|
138
|
-
log(`
|
|
137
|
+
log(` ${dim('→ Projeto novo: descreva o projeto ou forneça o PRD')}`);
|
|
138
|
+
log(` ${dim('→ Projeto existente: o agente escaneia o código automaticamente')}`);
|
|
139
|
+
log(` ${c.cyan}3.${c.reset} Revise os arquivos gerados e delete agents/SETUP.md`);
|
|
139
140
|
log();
|
|
140
141
|
|
|
141
142
|
if (harnessInstalled) {
|
|
@@ -267,18 +268,80 @@ async function update() {
|
|
|
267
268
|
log();
|
|
268
269
|
}
|
|
269
270
|
|
|
271
|
+
function nextSpecNumber(specsDir) {
|
|
272
|
+
if (!fs.existsSync(specsDir)) return '001';
|
|
273
|
+
const entries = fs.readdirSync(specsDir, { withFileTypes: true })
|
|
274
|
+
.filter(e => e.isDirectory())
|
|
275
|
+
.map(e => parseInt(e.name.slice(0, 3), 10))
|
|
276
|
+
.filter(n => !isNaN(n));
|
|
277
|
+
const max = entries.length ? Math.max(...entries) : 0;
|
|
278
|
+
return String(max + 1).padStart(3, '0');
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
function newSpec(rawName) {
|
|
282
|
+
log();
|
|
283
|
+
log(bold('sdd new'));
|
|
284
|
+
log();
|
|
285
|
+
|
|
286
|
+
const agentsDir = path.join(CWD, 'agents');
|
|
287
|
+
if (!fs.existsSync(agentsDir)) {
|
|
288
|
+
error('Pasta agents/ não encontrada. Rode ' + bold('sdd init') + ' primeiro.');
|
|
289
|
+
log();
|
|
290
|
+
process.exit(1);
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
if (!rawName) {
|
|
294
|
+
error('Informe o nome da feature: ' + bold('sdd new <nome-da-feature>'));
|
|
295
|
+
log(' Exemplo: ' + dim('sdd new user-authentication'));
|
|
296
|
+
log();
|
|
297
|
+
process.exit(1);
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
const name = rawName.toLowerCase().trim().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
|
|
301
|
+
if (!name) {
|
|
302
|
+
error('Nome inválido. Use apenas letras, números e hífens.');
|
|
303
|
+
log();
|
|
304
|
+
process.exit(1);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
const specsDir = path.join(agentsDir, 'specs');
|
|
308
|
+
const num = nextSpecNumber(specsDir);
|
|
309
|
+
const slug = num + '-' + name;
|
|
310
|
+
const specDir = path.join(specsDir, slug);
|
|
311
|
+
|
|
312
|
+
if (fs.existsSync(specDir)) {
|
|
313
|
+
error('Spec já existe: agents/specs/' + slug + '/');
|
|
314
|
+
log();
|
|
315
|
+
process.exit(1);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
fs.mkdirSync(specDir, { recursive: true });
|
|
319
|
+
fs.writeFileSync(
|
|
320
|
+
path.join(specDir, 'DECISIONS.md'),
|
|
321
|
+
'# DECISIONS — ' + name + '\n\n(decisões arquiteturais registradas durante o ciclo)\n'
|
|
322
|
+
);
|
|
323
|
+
|
|
324
|
+
ok('Spec criada: agents/specs/' + slug + '/');
|
|
325
|
+
log();
|
|
326
|
+
log(bold('Próximo passo — inicie a fase de Research:'));
|
|
327
|
+
log(' ' + c.cyan + '/sdd-research' + c.reset + ' ' + slug);
|
|
328
|
+
log(' ' + dim('"Leia e siga agents/prompts/rpi-research.md. Spec: ' + slug + '"'));
|
|
329
|
+
log();
|
|
330
|
+
}
|
|
331
|
+
|
|
270
332
|
function help() {
|
|
271
333
|
log();
|
|
272
334
|
log(bold('sdd-cli') + dim(' — Spec Driven Development workflow'));
|
|
273
335
|
log();
|
|
274
336
|
log('Uso:');
|
|
275
|
-
log(` sdd-cli ${c.cyan}init${c.reset}
|
|
276
|
-
log(` sdd-cli ${c.cyan}
|
|
277
|
-
log(` sdd-cli ${c.cyan}
|
|
278
|
-
log(` sdd-cli ${c.cyan}
|
|
279
|
-
log(` sdd-cli ${c.cyan}
|
|
337
|
+
log(` sdd-cli ${c.cyan}init${c.reset} Instala o workflow no projeto atual`);
|
|
338
|
+
log(` sdd-cli ${c.cyan}new <nome>${c.reset} Cria pasta da spec com numeração automática`);
|
|
339
|
+
log(` sdd-cli ${c.cyan}harness${c.reset} Instala, troca ou remove o harness do agente`);
|
|
340
|
+
log(` sdd-cli ${c.cyan}update${c.reset} Atualiza prompts e regras, preserva dados do projeto`);
|
|
341
|
+
log(` sdd-cli ${c.cyan}help${c.reset} Exibe esta mensagem`);
|
|
342
|
+
log(` sdd-cli ${c.cyan}--version${c.reset} Exibe a versão instalada`);
|
|
280
343
|
log();
|
|
281
|
-
log(dim(' Alias: sdd init / sdd harness / sdd update / sdd help / sdd --version'));
|
|
344
|
+
log(dim(' Alias: sdd init / sdd new / sdd harness / sdd update / sdd help / sdd --version'));
|
|
282
345
|
log();
|
|
283
346
|
log(dim(' Documentação: https://github.com/moisesuailab/spec-driven-workflow'));
|
|
284
347
|
log();
|
|
@@ -290,6 +353,9 @@ switch (cmd) {
|
|
|
290
353
|
case 'init':
|
|
291
354
|
init().catch(e => { error(e.message); process.exit(1); });
|
|
292
355
|
break;
|
|
356
|
+
case 'new':
|
|
357
|
+
newSpec(process.argv[3]);
|
|
358
|
+
break;
|
|
293
359
|
case 'harness':
|
|
294
360
|
harness().catch(e => { error(e.message); process.exit(1); });
|
|
295
361
|
break;
|
package/package.json
CHANGED
|
@@ -1,32 +1,32 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "sdd-flow",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Spec Driven Development workflow for AI-assisted development (SDD + RPI)",
|
|
5
|
-
"bin": {
|
|
6
|
-
"sdd-cli": "
|
|
7
|
-
"sdd":
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"templates/"
|
|
12
|
-
],
|
|
13
|
-
"engines": {
|
|
14
|
-
"node": ">=18"
|
|
15
|
-
},
|
|
16
|
-
"keywords": [
|
|
17
|
-
"sdd",
|
|
18
|
-
"spec-driven-development",
|
|
19
|
-
"rpi",
|
|
20
|
-
"ai-workflow",
|
|
21
|
-
"claude-code",
|
|
22
|
-
"opencode",
|
|
23
|
-
"agentic",
|
|
24
|
-
"workflow"
|
|
25
|
-
],
|
|
26
|
-
"author": "moisesuailab",
|
|
27
|
-
"license": "MIT",
|
|
28
|
-
"repository": {
|
|
29
|
-
"type": "git",
|
|
30
|
-
"url": "https://github.com/moisesuailab/
|
|
31
|
-
}
|
|
32
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "sdd-flow",
|
|
3
|
+
"version": "1.2.5",
|
|
4
|
+
"description": "Spec Driven Development workflow for AI-assisted development (SDD + RPI)",
|
|
5
|
+
"bin": {
|
|
6
|
+
"sdd-cli": "bin/cli.js",
|
|
7
|
+
"sdd": "bin/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"templates/"
|
|
12
|
+
],
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"sdd",
|
|
18
|
+
"spec-driven-development",
|
|
19
|
+
"rpi",
|
|
20
|
+
"ai-workflow",
|
|
21
|
+
"claude-code",
|
|
22
|
+
"opencode",
|
|
23
|
+
"agentic",
|
|
24
|
+
"workflow"
|
|
25
|
+
],
|
|
26
|
+
"author": "moisesuailab",
|
|
27
|
+
"license": "MIT",
|
|
28
|
+
"repository": {
|
|
29
|
+
"type": "git",
|
|
30
|
+
"url": "https://github.com/moisesuailab/sdd-flow.git"
|
|
31
|
+
}
|
|
32
|
+
}
|
package/templates/QUICKSTART.md
CHANGED
|
@@ -1,50 +1,70 @@
|
|
|
1
|
-
# SDD Workflow
|
|
1
|
+
# SDD Workflow - Quick Start
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Cycle
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Each feature goes through 4 phases in isolated sessions:
|
|
6
6
|
|
|
7
7
|
```
|
|
8
8
|
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Initial setup
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
After running `sdd init`, open your agent in the project and instruct:
|
|
14
14
|
|
|
15
15
|
```
|
|
16
|
-
|
|
17
|
-
/sdd-plan 001-nome-da-feature → produz SPEC.md + TASK.md + TEST.md
|
|
18
|
-
/sdd-implement 001-nome-da-feature → implementa uma task por vez
|
|
19
|
-
/sdd-validate 001-nome-da-feature → produz VALIDATION.md
|
|
16
|
+
"Read and follow agents/SETUP.md"
|
|
20
17
|
```
|
|
21
18
|
|
|
22
|
-
|
|
19
|
+
- **New project:** describe the project or provide the PRD — the agent generates PROJECT.md and the skills
|
|
20
|
+
- **Existing project:** the agent scans the code automatically
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
Review the generated files and delete `agents/SETUP.md`.
|
|
25
23
|
|
|
24
|
+
## Starting a feature
|
|
25
|
+
|
|
26
|
+
### With slash commands
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
/sdd-research 001-feature-name → produces RESEARCH.md
|
|
30
|
+
/sdd-plan 001-feature-name → produces SPEC.md + TASK.md + TEST.md
|
|
31
|
+
/sdd-implement 001-feature-name → implements one task at a time
|
|
32
|
+
/sdd-validate 001-feature-name → produces VALIDATION.md
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Without slash commands
|
|
36
|
+
|
|
37
|
+
Instruct your agent in each session:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
"Read and follow agents/prompts/rpi-research.md. Spec: 001-feature-name"
|
|
41
|
+
"Read and follow agents/prompts/rpi-plan.md. Spec: 001-feature-name"
|
|
42
|
+
"Read and follow agents/prompts/rpi-implement.md. Spec: 001-feature-name"
|
|
43
|
+
"Read and follow agents/prompts/rpi-validate.md. Spec: 001-feature-name"
|
|
26
44
|
```
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
45
|
+
|
|
46
|
+
## Creating a new spec
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
sdd new feature-name
|
|
50
|
+
# ✔ Spec created: agents/specs/001-feature-name/
|
|
31
51
|
```
|
|
32
52
|
|
|
33
|
-
##
|
|
53
|
+
## Spec structure after the full cycle
|
|
34
54
|
|
|
35
55
|
```
|
|
36
|
-
agents/specs/001-
|
|
37
|
-
RESEARCH.md ←
|
|
38
|
-
SPEC.md ←
|
|
39
|
-
TASK.md ←
|
|
40
|
-
TEST.md ←
|
|
41
|
-
PROGRESS.md ←
|
|
42
|
-
DECISIONS.md ←
|
|
43
|
-
VALIDATION.md ←
|
|
56
|
+
agents/specs/001-feature-name/
|
|
57
|
+
RESEARCH.md ← phase 1
|
|
58
|
+
SPEC.md ← phase 2
|
|
59
|
+
TASK.md ← phase 2
|
|
60
|
+
TEST.md ← phase 2
|
|
61
|
+
PROGRESS.md ← updated in phase 3
|
|
62
|
+
DECISIONS.md ← architectural decisions
|
|
63
|
+
VALIDATION.md ← phase 4
|
|
44
64
|
```
|
|
45
65
|
|
|
46
|
-
##
|
|
66
|
+
## References
|
|
47
67
|
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
68
|
+
- Process rules → `agents/RULES.md`
|
|
69
|
+
- Full workflow definition → `agents/AGENTS.md`
|
|
70
|
+
- Documentation → https://github.com/moisesuailab/sdd-flow
|
|
@@ -1,92 +1,92 @@
|
|
|
1
|
-
# AGENTS.md
|
|
2
|
-
|
|
3
|
-
> This file is the full workflow definition. It is referenced by the root `AGENTS.md`.
|
|
4
|
-
> Do not modify the root file — extend rules here or in `RULES.md`.
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## Agent Role
|
|
9
|
-
|
|
10
|
-
You are a senior developer working on this project. Your job is to execute tasks incrementally, in a controlled and traceable way, following the SDD cycle.
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## Files to always read first
|
|
15
|
-
|
|
16
|
-
Before any action, read:
|
|
17
|
-
|
|
18
|
-
1. `agents/PROJECT.md` — stack, file structure, architecture patterns and stack rules
|
|
19
|
-
2. `agents/RULES.md` — mandatory process rules
|
|
20
|
-
3. `agents/DECISIONS.md` — architectural decisions already made
|
|
21
|
-
|
|
22
|
-
> Requirements (PRD or equivalent) are provided by the developer during the Research phase.
|
|
23
|
-
> From the Plan phase onward, `RESEARCH.md` replaces the PRD as the source of truth for that feature.
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## SDD Cycle
|
|
28
|
-
|
|
29
|
-
Each phase runs in an **isolated session**. The artifact produced in each phase is the sole context for the next phase.
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
| Phase | Prompt | Reads | Produces |
|
|
36
|
-
|---|---|---|---|
|
|
37
|
-
| Research | `rpi-research.md` | `PROJECT.md` + `RULES.md` + requirements | `RESEARCH.md` |
|
|
38
|
-
| Plan | `rpi-plan.md` | `PROJECT.md` + `RULES.md` + `RESEARCH.md` | `SPEC.md` + `TASK.md` + `PROGRESS.md` + `TEST.md` |
|
|
39
|
-
| Implement | `rpi-implement.md` | `PROJECT.md` + `RULES.md` + `SPEC.md` + `TASK.md` + `PROGRESS.md` + relevant skill(s)¹ | code + updated `TASK.md` + updated `PROGRESS.md` |
|
|
40
|
-
| Validate | `rpi-validate.md` | `SPEC.md` + `TASK.md` + `TEST.md` + `PROGRESS.md` + produced code | `VALIDATION.md` |
|
|
41
|
-
|
|
42
|
-
> ¹ Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to scan skill descriptions. Load the full `SKILL.md` only for skills relevant to the task.
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## Spec Structure
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
agents/specs/NNN-feature-name/
|
|
50
|
-
RESEARCH.md — compressed understanding of the feature (produced in Research)
|
|
51
|
-
SPEC.md — functional requirements, business rules, UI section (produced in Plan)
|
|
52
|
-
TASK.md — task breakdown derived from the spec (produced in Plan)
|
|
53
|
-
PROGRESS.md — current execution state (produced in Plan, updated in Implement)
|
|
54
|
-
DECISIONS.md — feature-local decisions (updated as needed)
|
|
55
|
-
TEST.md — acceptance test cases in given/when/then format (produced in Plan)
|
|
56
|
-
VALIDATION.md — coverage matrix and approval status (produced in Validate)
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## Before implementing a task
|
|
62
|
-
|
|
63
|
-
1. Read the feature's `SPEC.md`
|
|
64
|
-
2. Read `TASK.md` and identify the current task (first unchecked `[ ]`)
|
|
65
|
-
3. Read `PROGRESS.md` to understand the current state
|
|
66
|
-
4. Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to read only the "When to use" section of each skill. Load the full `SKILL.md` only for skills relevant to this task.
|
|
67
|
-
5. If there is ambiguity, **ask before generating code**
|
|
68
|
-
|
|
69
|
-
---
|
|
70
|
-
|
|
71
|
-
## After implementing a task
|
|
72
|
-
|
|
73
|
-
1. Mark `[x]` on the task in `TASK.md`
|
|
74
|
-
2. Update `PROGRESS.md` with what was done and any observations
|
|
75
|
-
3. If an architectural decision was made, record it in `DECISIONS.md`
|
|
76
|
-
4. **Stop and wait for confirmation** before moving to the next task
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
## Behavioral rules
|
|
81
|
-
|
|
82
|
-
- Never implement more than one task at a time
|
|
83
|
-
- Never run git commands (commit, push, tag, branch)
|
|
84
|
-
- Never modify `agents/PROJECT.md` or `agents/RULES.md` without explicit request
|
|
85
|
-
- When in doubt about scope: ask, do not assume
|
|
86
|
-
- If a simpler approach exists than what is specified, mention it before implementing — never build in silence when a more direct solution is available
|
|
87
|
-
|
|
88
|
-
## Output Language
|
|
89
|
-
- Code and identifiers: English
|
|
90
|
-
- Agent explanations and responses: Portuguese (Brazil)
|
|
91
|
-
- Commit messages: English
|
|
92
|
-
- UI-facing strings (labels, messages, placeholders): Portuguese (Brazil)
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
> This file is the full workflow definition. It is referenced by the root `AGENTS.md`.
|
|
4
|
+
> Do not modify the root file — extend rules here or in `RULES.md`.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Agent Role
|
|
9
|
+
|
|
10
|
+
You are a senior developer working on this project. Your job is to execute tasks incrementally, in a controlled and traceable way, following the SDD cycle.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Files to always read first
|
|
15
|
+
|
|
16
|
+
Before any action, read:
|
|
17
|
+
|
|
18
|
+
1. `agents/PROJECT.md` — stack, file structure, architecture patterns and stack rules
|
|
19
|
+
2. `agents/RULES.md` — mandatory process rules
|
|
20
|
+
3. `agents/DECISIONS.md` — architectural decisions already made
|
|
21
|
+
|
|
22
|
+
> Requirements (PRD or equivalent) are provided by the developer during the Research phase.
|
|
23
|
+
> From the Plan phase onward, `RESEARCH.md` replaces the PRD as the source of truth for that feature.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## SDD Cycle
|
|
28
|
+
|
|
29
|
+
Each phase runs in an **isolated session**. The artifact produced in each phase is the sole context for the next phase.
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
| Phase | Prompt | Reads | Produces |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| Research | `rpi-research.md` | `PROJECT.md` + `RULES.md` + requirements | `RESEARCH.md` |
|
|
38
|
+
| Plan | `rpi-plan.md` | `PROJECT.md` + `RULES.md` + `RESEARCH.md` | `SPEC.md` + `TASK.md` + `PROGRESS.md` + `TEST.md` |
|
|
39
|
+
| Implement | `rpi-implement.md` | `PROJECT.md` + `RULES.md` + `SPEC.md` + `TASK.md` + `PROGRESS.md` + relevant skill(s)¹ | code + updated `TASK.md` + updated `PROGRESS.md` |
|
|
40
|
+
| Validate | `rpi-validate.md` | `SPEC.md` + `TASK.md` + `TEST.md` + `PROGRESS.md` + produced code | `VALIDATION.md` |
|
|
41
|
+
|
|
42
|
+
> ¹ Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to scan skill descriptions. Load the full `SKILL.md` only for skills relevant to the task.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Spec Structure
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
agents/specs/NNN-feature-name/
|
|
50
|
+
RESEARCH.md — compressed understanding of the feature (produced in Research)
|
|
51
|
+
SPEC.md — functional requirements, business rules, UI section (produced in Plan)
|
|
52
|
+
TASK.md — task breakdown derived from the spec (produced in Plan)
|
|
53
|
+
PROGRESS.md — current execution state (produced in Plan, updated in Implement)
|
|
54
|
+
DECISIONS.md — feature-local decisions (updated as needed)
|
|
55
|
+
TEST.md — acceptance test cases in given/when/then format (produced in Plan)
|
|
56
|
+
VALIDATION.md — coverage matrix and approval status (produced in Validate)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Before implementing a task
|
|
62
|
+
|
|
63
|
+
1. Read the feature's `SPEC.md`
|
|
64
|
+
2. Read `TASK.md` and identify the current task (first unchecked `[ ]`)
|
|
65
|
+
3. Read `PROGRESS.md` to understand the current state
|
|
66
|
+
4. Run `grep -A 8 "## When to use" agents/skills/*/SKILL.md` to read only the "When to use" section of each skill. Load the full `SKILL.md` only for skills relevant to this task.
|
|
67
|
+
5. If there is ambiguity, **ask before generating code**
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## After implementing a task
|
|
72
|
+
|
|
73
|
+
1. Mark `[x]` on the task in `TASK.md`
|
|
74
|
+
2. Update `PROGRESS.md` with what was done and any observations
|
|
75
|
+
3. If an architectural decision was made, record it in `DECISIONS.md`
|
|
76
|
+
4. **Stop and wait for confirmation** before moving to the next task
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Behavioral rules
|
|
81
|
+
|
|
82
|
+
- Never implement more than one task at a time
|
|
83
|
+
- Never run git commands (commit, push, tag, branch)
|
|
84
|
+
- Never modify `agents/PROJECT.md` or `agents/RULES.md` without explicit request
|
|
85
|
+
- When in doubt about scope: ask, do not assume
|
|
86
|
+
- If a simpler approach exists than what is specified, mention it before implementing — never build in silence when a more direct solution is available
|
|
87
|
+
|
|
88
|
+
## Output Language
|
|
89
|
+
- Code and identifiers: English
|
|
90
|
+
- Agent explanations and responses: Portuguese (Brazil)
|
|
91
|
+
- Commit messages: English
|
|
92
|
+
- UI-facing strings (labels, messages, placeholders): Portuguese (Brazil)
|