sdd-flow 1.0.0 → 1.2.4
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 +83 -83
- package/bin/cli.js +380 -315
- package/package.json +32 -32
- package/templates/QUICKSTART.md +50 -50
- 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/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/spec-
|
|
31
|
-
}
|
|
32
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "sdd-flow",
|
|
3
|
+
"version": "1.2.4",
|
|
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": "git+https://github.com/moisesuailab/spec-workflow-cli.git"
|
|
31
|
+
}
|
|
32
|
+
}
|
package/templates/QUICKSTART.md
CHANGED
|
@@ -1,50 +1,50 @@
|
|
|
1
|
-
# SDD Workflow — Quick Start
|
|
2
|
-
|
|
3
|
-
## Ciclo
|
|
4
|
-
|
|
5
|
-
Cada feature passa por 4 fases em sessões isoladas:
|
|
6
|
-
|
|
7
|
-
```
|
|
8
|
-
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
## Iniciando uma feature
|
|
12
|
-
|
|
13
|
-
### Com slash commands
|
|
14
|
-
|
|
15
|
-
```
|
|
16
|
-
/sdd-research 001-nome-da-feature → produz RESEARCH.md
|
|
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
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
### Sem slash commands
|
|
23
|
-
|
|
24
|
-
Instrua seu agente em cada sessão:
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
"Leia e siga agents/prompts/rpi-research.md. Spec: 001-nome-da-feature"
|
|
28
|
-
"Leia e siga agents/prompts/rpi-plan.md. Spec: 001-nome-da-feature"
|
|
29
|
-
"Leia e siga agents/prompts/rpi-implement.md. Spec: 001-nome-da-feature"
|
|
30
|
-
"Leia e siga agents/prompts/rpi-validate.md. Spec: 001-nome-da-feature"
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
## Estrutura da spec após o ciclo completo
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
agents/specs/001-nome-da-feature/
|
|
37
|
-
RESEARCH.md ← fase 1
|
|
38
|
-
SPEC.md ← fase 2
|
|
39
|
-
TASK.md ← fase 2
|
|
40
|
-
TEST.md ← fase 2
|
|
41
|
-
PROGRESS.md ← atualizado na fase 3
|
|
42
|
-
DECISIONS.md ← decisões arquiteturais
|
|
43
|
-
VALIDATION.md ← fase 4
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
## Referências
|
|
47
|
-
|
|
48
|
-
- Regras do processo → `agents/RULES.md`
|
|
49
|
-
- Definição completa do workflow → `agents/AGENTS.md`
|
|
50
|
-
- Documentação → https://github.com/moisesuailab/spec-driven-workflow
|
|
1
|
+
# SDD Workflow — Quick Start
|
|
2
|
+
|
|
3
|
+
## Ciclo
|
|
4
|
+
|
|
5
|
+
Cada feature passa por 4 fases em sessões isoladas:
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
RESEARCH → PLAN → IMPLEMENT → VALIDATE
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Iniciando uma feature
|
|
12
|
+
|
|
13
|
+
### Com slash commands
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
/sdd-research 001-nome-da-feature → produz RESEARCH.md
|
|
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
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
### Sem slash commands
|
|
23
|
+
|
|
24
|
+
Instrua seu agente em cada sessão:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
"Leia e siga agents/prompts/rpi-research.md. Spec: 001-nome-da-feature"
|
|
28
|
+
"Leia e siga agents/prompts/rpi-plan.md. Spec: 001-nome-da-feature"
|
|
29
|
+
"Leia e siga agents/prompts/rpi-implement.md. Spec: 001-nome-da-feature"
|
|
30
|
+
"Leia e siga agents/prompts/rpi-validate.md. Spec: 001-nome-da-feature"
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Estrutura da spec após o ciclo completo
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
agents/specs/001-nome-da-feature/
|
|
37
|
+
RESEARCH.md ← fase 1
|
|
38
|
+
SPEC.md ← fase 2
|
|
39
|
+
TASK.md ← fase 2
|
|
40
|
+
TEST.md ← fase 2
|
|
41
|
+
PROGRESS.md ← atualizado na fase 3
|
|
42
|
+
DECISIONS.md ← decisões arquiteturais
|
|
43
|
+
VALIDATION.md ← fase 4
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Referências
|
|
47
|
+
|
|
48
|
+
- Regras do processo → `agents/RULES.md`
|
|
49
|
+
- Definição completa do workflow → `agents/AGENTS.md`
|
|
50
|
+
- Documentação → https://github.com/moisesuailab/spec-driven-workflow
|
|
@@ -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)
|
|
@@ -1,116 +1,116 @@
|
|
|
1
|
-
# RULES.md — Mandatory Process Rules
|
|
2
|
-
|
|
3
|
-
This file defines process rules that apply to every project regardless of stack.
|
|
4
|
-
Stack-specific rules belong in `PROJECT.md` under the **Stack Rules** section.
|
|
5
|
-
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
## Implementation Rules
|
|
9
|
-
|
|
10
|
-
### R01 — No implementation without a spec
|
|
11
|
-
No meaningful code change may be made without:
|
|
12
|
-
- An existing `SPEC.md`
|
|
13
|
-
- An existing `TASK.md`
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
### R02 — One task at a time
|
|
18
|
-
Always implement exactly ONE isolated task.
|
|
19
|
-
Never implement multiple tasks in the same step.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
### R03 — Update PROGRESS.md on every task completion
|
|
24
|
-
When any task is completed:
|
|
25
|
-
- Update the task status (Pending → Done)
|
|
26
|
-
- Record relevant observations in the History section
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
### R04 — Mark completed tasks in TASK.md
|
|
31
|
-
When any task is completed:
|
|
32
|
-
- Replace `[ ]` with `[x]` in the corresponding TASK.md
|
|
33
|
-
- TASK.md must always reflect the real state of PROGRESS.md
|
|
34
|
-
|
|
35
|
-
---
|
|
36
|
-
|
|
37
|
-
### R05 — Record relevant decisions
|
|
38
|
-
Architectural changes must be recorded in:
|
|
39
|
-
- `agents/DECISIONS.md` — global decisions
|
|
40
|
-
- `agents/specs/.../DECISIONS.md` — feature-local decisions
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## Git Rules
|
|
45
|
-
|
|
46
|
-
### R06 — Never run git commands automatically
|
|
47
|
-
Agents must NEVER:
|
|
48
|
-
- Create commits
|
|
49
|
-
- Create tags or releases
|
|
50
|
-
- Push to any remote
|
|
51
|
-
- Create or switch branches
|
|
52
|
-
|
|
53
|
-
The agent only prepares code changes. The developer runs git manually.
|
|
54
|
-
|
|
55
|
-
**Reason:** Human control over history and releases is mandatory.
|
|
56
|
-
|
|
57
|
-
---
|
|
58
|
-
|
|
59
|
-
## Code Quality Rules
|
|
60
|
-
|
|
61
|
-
### R07 — Prefer simple and predictable code
|
|
62
|
-
Avoid unnecessary abstractions. Optimize for readability and maintainability.
|
|
63
|
-
|
|
64
|
-
---
|
|
65
|
-
|
|
66
|
-
### R08 — No new external dependencies without justification
|
|
67
|
-
Do not add libraries or packages without:
|
|
68
|
-
- A clear justification
|
|
69
|
-
- A record in `DECISIONS.md`
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
### R09 — No auto-generated comments or JSDoc
|
|
74
|
-
Do not add explanatory comments or documentation blocks unless:
|
|
75
|
-
- Explicitly requested in the prompt, or
|
|
76
|
-
- Strictly necessary to fix an error or maintain consistency
|
|
77
|
-
|
|
78
|
-
**Reason:** Avoid code noise and documentation drift.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## Roadmap Rules
|
|
83
|
-
|
|
84
|
-
### R10 — Every feature must have a spec
|
|
85
|
-
Every feature on the roadmap must have a corresponding spec folder in `agents/specs/`.
|
|
86
|
-
|
|
87
|
-
---
|
|
88
|
-
|
|
89
|
-
## Scope Rules
|
|
90
|
-
|
|
91
|
-
### R11 — Do not refactor outside the task scope
|
|
92
|
-
Do not touch code unrelated to the current task, even if it looks improvable.
|
|
93
|
-
Remove imports, variables, or functions that **your changes** made unused.
|
|
94
|
-
Do not remove pre-existing dead code unless explicitly requested.
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
### R12 — Do not anticipate future tasks
|
|
99
|
-
Only implement what the current task requires.
|
|
100
|
-
Do not build ahead for tasks not yet started.
|
|
101
|
-
|
|
102
|
-
---
|
|
103
|
-
|
|
104
|
-
### R13 — Follow core coding principles
|
|
105
|
-
Every generated code must follow:
|
|
106
|
-
- **KISS** — simplest solution that solves the problem. No over-engineering.
|
|
107
|
-
- **DRY** — never duplicate logic. Extract to shared helpers or services.
|
|
108
|
-
- **Clean Code** — descriptive names, small functions, single responsibility.
|
|
109
|
-
- **SOLID** — each module owns one concern. Entry points delegate, never contain logic.
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
### R14 — Surface ambiguities before choosing
|
|
114
|
-
If a requirement has multiple valid interpretations, list them explicitly
|
|
115
|
-
before choosing one. Never pick silently. If the ambiguity blocks progress,
|
|
116
|
-
stop and ask before generating any code.
|
|
1
|
+
# RULES.md — Mandatory Process Rules
|
|
2
|
+
|
|
3
|
+
This file defines process rules that apply to every project regardless of stack.
|
|
4
|
+
Stack-specific rules belong in `PROJECT.md` under the **Stack Rules** section.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Implementation Rules
|
|
9
|
+
|
|
10
|
+
### R01 — No implementation without a spec
|
|
11
|
+
No meaningful code change may be made without:
|
|
12
|
+
- An existing `SPEC.md`
|
|
13
|
+
- An existing `TASK.md`
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
### R02 — One task at a time
|
|
18
|
+
Always implement exactly ONE isolated task.
|
|
19
|
+
Never implement multiple tasks in the same step.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
### R03 — Update PROGRESS.md on every task completion
|
|
24
|
+
When any task is completed:
|
|
25
|
+
- Update the task status (Pending → Done)
|
|
26
|
+
- Record relevant observations in the History section
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
### R04 — Mark completed tasks in TASK.md
|
|
31
|
+
When any task is completed:
|
|
32
|
+
- Replace `[ ]` with `[x]` in the corresponding TASK.md
|
|
33
|
+
- TASK.md must always reflect the real state of PROGRESS.md
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
### R05 — Record relevant decisions
|
|
38
|
+
Architectural changes must be recorded in:
|
|
39
|
+
- `agents/DECISIONS.md` — global decisions
|
|
40
|
+
- `agents/specs/.../DECISIONS.md` — feature-local decisions
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Git Rules
|
|
45
|
+
|
|
46
|
+
### R06 — Never run git commands automatically
|
|
47
|
+
Agents must NEVER:
|
|
48
|
+
- Create commits
|
|
49
|
+
- Create tags or releases
|
|
50
|
+
- Push to any remote
|
|
51
|
+
- Create or switch branches
|
|
52
|
+
|
|
53
|
+
The agent only prepares code changes. The developer runs git manually.
|
|
54
|
+
|
|
55
|
+
**Reason:** Human control over history and releases is mandatory.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Code Quality Rules
|
|
60
|
+
|
|
61
|
+
### R07 — Prefer simple and predictable code
|
|
62
|
+
Avoid unnecessary abstractions. Optimize for readability and maintainability.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
### R08 — No new external dependencies without justification
|
|
67
|
+
Do not add libraries or packages without:
|
|
68
|
+
- A clear justification
|
|
69
|
+
- A record in `DECISIONS.md`
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
### R09 — No auto-generated comments or JSDoc
|
|
74
|
+
Do not add explanatory comments or documentation blocks unless:
|
|
75
|
+
- Explicitly requested in the prompt, or
|
|
76
|
+
- Strictly necessary to fix an error or maintain consistency
|
|
77
|
+
|
|
78
|
+
**Reason:** Avoid code noise and documentation drift.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Roadmap Rules
|
|
83
|
+
|
|
84
|
+
### R10 — Every feature must have a spec
|
|
85
|
+
Every feature on the roadmap must have a corresponding spec folder in `agents/specs/`.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Scope Rules
|
|
90
|
+
|
|
91
|
+
### R11 — Do not refactor outside the task scope
|
|
92
|
+
Do not touch code unrelated to the current task, even if it looks improvable.
|
|
93
|
+
Remove imports, variables, or functions that **your changes** made unused.
|
|
94
|
+
Do not remove pre-existing dead code unless explicitly requested.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
### R12 — Do not anticipate future tasks
|
|
99
|
+
Only implement what the current task requires.
|
|
100
|
+
Do not build ahead for tasks not yet started.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### R13 — Follow core coding principles
|
|
105
|
+
Every generated code must follow:
|
|
106
|
+
- **KISS** — simplest solution that solves the problem. No over-engineering.
|
|
107
|
+
- **DRY** — never duplicate logic. Extract to shared helpers or services.
|
|
108
|
+
- **Clean Code** — descriptive names, small functions, single responsibility.
|
|
109
|
+
- **SOLID** — each module owns one concern. Entry points delegate, never contain logic.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
### R14 — Surface ambiguities before choosing
|
|
114
|
+
If a requirement has multiple valid interpretations, list them explicitly
|
|
115
|
+
before choosing one. Never pick silently. If the ambiguity blocks progress,
|
|
116
|
+
stop and ask before generating any code.
|
|
@@ -1,22 +1,22 @@
|
|
|
1
|
-
#!/bin/bash
|
|
2
|
-
# guard-delete.sh
|
|
3
|
-
# Asks for confirmation before running destructive delete commands (rm -rf, rm -r, rm -f).
|
|
4
|
-
# Exit 0 = allow | Exit 2 = block (Claude Code convention)
|
|
5
|
-
|
|
6
|
-
INPUT=$(cat)
|
|
7
|
-
|
|
8
|
-
COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | sed 's/"command":"//;s/"//')
|
|
9
|
-
|
|
10
|
-
# Intercept rm with recursive or force flags
|
|
11
|
-
if echo "$COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*[rf][a-zA-Z]*|--recursive|--force)"; then
|
|
12
|
-
echo "⚠️ Agent wants to run: $COMMAND" >&2
|
|
13
|
-
read -r -p "Allow destructive delete? [y/N] " response < /dev/tty
|
|
14
|
-
if [[ "$response" =~ ^[Yy]$ ]]; then
|
|
15
|
-
exit 0
|
|
16
|
-
else
|
|
17
|
-
echo "Blocked by guard-delete.sh" >&2
|
|
18
|
-
exit 2
|
|
19
|
-
fi
|
|
20
|
-
fi
|
|
21
|
-
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# guard-delete.sh
|
|
3
|
+
# Asks for confirmation before running destructive delete commands (rm -rf, rm -r, rm -f).
|
|
4
|
+
# Exit 0 = allow | Exit 2 = block (Claude Code convention)
|
|
5
|
+
|
|
6
|
+
INPUT=$(cat)
|
|
7
|
+
|
|
8
|
+
COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | sed 's/"command":"//;s/"//')
|
|
9
|
+
|
|
10
|
+
# Intercept rm with recursive or force flags
|
|
11
|
+
if echo "$COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*[rf][a-zA-Z]*|--recursive|--force)"; then
|
|
12
|
+
echo "⚠️ Agent wants to run: $COMMAND" >&2
|
|
13
|
+
read -r -p "Allow destructive delete? [y/N] " response < /dev/tty
|
|
14
|
+
if [[ "$response" =~ ^[Yy]$ ]]; then
|
|
15
|
+
exit 0
|
|
16
|
+
else
|
|
17
|
+
echo "Blocked by guard-delete.sh" >&2
|
|
18
|
+
exit 2
|
|
19
|
+
fi
|
|
20
|
+
fi
|
|
21
|
+
|
|
22
22
|
exit 0
|