sdd-flow 1.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.
- package/LICENSE +21 -0
- package/README.md +83 -0
- package/bin/cli.js +315 -0
- package/package.json +32 -0
- package/templates/AGENTS.md +49 -0
- package/templates/QUICKSTART.md +50 -0
- package/templates/agents/AGENTS.md +92 -0
- package/templates/agents/DECISIONS.md +21 -0
- package/templates/agents/PROJECT.md +145 -0
- package/templates/agents/RULES.md +116 -0
- package/templates/agents/SETUP.md +224 -0
- package/templates/agents/harness/claude-code/.hooks/guard-delete.sh +22 -0
- package/templates/agents/harness/claude-code/.hooks/guard-deps.sh +25 -0
- package/templates/agents/harness/claude-code/.hooks/guard-git.sh +24 -0
- package/templates/agents/harness/claude-code/commands/sdd-implement.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-plan.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-research.md +3 -0
- package/templates/agents/harness/claude-code/commands/sdd-validate.md +3 -0
- package/templates/agents/harness/claude-code/settings.json +34 -0
- package/templates/agents/harness/opencode/commands/sdd-implement.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-plan.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-research.md +3 -0
- package/templates/agents/harness/opencode/commands/sdd-validate.md +3 -0
- package/templates/agents/harness/opencode/opencode.json +18 -0
- package/templates/agents/prompts/conventional-commit.md +51 -0
- package/templates/agents/prompts/pr-template.md +21 -0
- package/templates/agents/prompts/rpi-implement.md +46 -0
- package/templates/agents/prompts/rpi-plan.md +117 -0
- package/templates/agents/prompts/rpi-research.md +67 -0
- package/templates/agents/prompts/rpi-validate.md +96 -0
- package/templates/agents/prompts/skill-call.md +29 -0
- package/templates/agents/prompts/task-create.md +42 -0
- package/templates/agents/skills/_template/SKILL.md +37 -0
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# PROJECT.md
|
|
2
|
+
|
|
3
|
+
<!--
|
|
4
|
+
⚠️ SETUP REQUIRED
|
|
5
|
+
Replace every [FILL: ...] with your project's actual content.
|
|
6
|
+
Delete all comments (<!-- ... -->) when done.
|
|
7
|
+
This file is read by the agent in EVERY session — keep it dense and scannable.
|
|
8
|
+
-->
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
[FILL: 1–2 sentences describing what the project does and the problem it solves]
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Stack
|
|
17
|
+
|
|
18
|
+
<!--
|
|
19
|
+
List every layer of the stack. Add or remove rows as needed.
|
|
20
|
+
Examples per layer:
|
|
21
|
+
Runtime: Node.js 20, Python 3.12, Google Apps Script V8, Deno
|
|
22
|
+
Framework: Express, FastAPI, NestJS, Django, none
|
|
23
|
+
Persistence: PostgreSQL, MongoDB, Redis, Google Sheets, SQLite
|
|
24
|
+
Frontend: React + Tailwind, Vue 3, Alpine.js + Tailwind, plain HTML
|
|
25
|
+
Auth: JWT, OAuth2, session-based, built-in roles
|
|
26
|
+
Testing: Jest, Pytest, Vitest, manual
|
|
27
|
+
Deployment: Docker + Railway, Vercel, GCP, manual
|
|
28
|
+
-->
|
|
29
|
+
|
|
30
|
+
| Layer | Technology |
|
|
31
|
+
|---|---|
|
|
32
|
+
| Runtime | [FILL: e.g. Node.js 20] |
|
|
33
|
+
| Framework | [FILL: e.g. Express 4] |
|
|
34
|
+
| Persistence | [FILL: e.g. PostgreSQL 16] |
|
|
35
|
+
| Frontend | [FILL: e.g. React 18 + Tailwind CSS 3] |
|
|
36
|
+
| Auth | [FILL: e.g. JWT via jsonwebtoken] |
|
|
37
|
+
| Testing | [FILL: e.g. Vitest] |
|
|
38
|
+
| Deployment | [FILL: e.g. Docker + Railway] |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## File / Module Structure
|
|
43
|
+
|
|
44
|
+
<!--
|
|
45
|
+
List the key files/directories and their responsibility.
|
|
46
|
+
Agents use this to know WHERE to look and WHERE to write.
|
|
47
|
+
Be explicit. Ambiguity here causes agents to create files in wrong places.
|
|
48
|
+
|
|
49
|
+
Example (Node/Express):
|
|
50
|
+
src/
|
|
51
|
+
routes/ — Express route handlers (entry point for HTTP requests)
|
|
52
|
+
services/ — Business logic and orchestration
|
|
53
|
+
repositories/ — Data access layer (DB queries)
|
|
54
|
+
middlewares/ — Auth guards, validation, error handling
|
|
55
|
+
config/ — Environment variables and constants
|
|
56
|
+
tests/ — Unit and integration tests (mirrors src/ structure)
|
|
57
|
+
index.ts — App entry point
|
|
58
|
+
-->
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
[FILL: paste your actual file/directory tree with a one-line description per entry]
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Architecture Patterns
|
|
67
|
+
|
|
68
|
+
<!--
|
|
69
|
+
Describe the patterns the codebase follows.
|
|
70
|
+
Agents must know these to avoid violating them when generating code.
|
|
71
|
+
|
|
72
|
+
Examples:
|
|
73
|
+
- Layered architecture: route → service → repository
|
|
74
|
+
- Repository pattern: all DB access goes through repository classes
|
|
75
|
+
- Response envelope: all API responses use { status, data, message }
|
|
76
|
+
- Error handling: all errors thrown as AppError and caught by global middleware
|
|
77
|
+
-->
|
|
78
|
+
|
|
79
|
+
[FILL: describe 3–5 architectural patterns enforced in this project]
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Stack Rules
|
|
84
|
+
|
|
85
|
+
<!--
|
|
86
|
+
Rules specific to your stack that agents must follow.
|
|
87
|
+
These complement the generic rules in RULES.md.
|
|
88
|
+
Write each rule as: ### SR-NN — Title + explanation + reason.
|
|
89
|
+
|
|
90
|
+
Examples to adapt:
|
|
91
|
+
|
|
92
|
+
### SR-01 — All DB access through the repository layer
|
|
93
|
+
Never call the ORM/DB client directly from services or routes.
|
|
94
|
+
Always go through the repository class for the entity.
|
|
95
|
+
Reason: consistent data access, easy to mock in tests.
|
|
96
|
+
|
|
97
|
+
### SR-02 — No raw SQL outside repository files
|
|
98
|
+
Do not write raw SQL queries in services, routes, or controllers.
|
|
99
|
+
Reason: keeps query logic centralized and auditable.
|
|
100
|
+
|
|
101
|
+
### SR-03 — All API responses use the standard envelope
|
|
102
|
+
Every endpoint must return { status, data, message }.
|
|
103
|
+
Use the shared createResponse() helper — do not build the object manually.
|
|
104
|
+
|
|
105
|
+
### SR-04 — Environment variables only via config/
|
|
106
|
+
Never read process.env directly outside of config/ files.
|
|
107
|
+
Reason: centralized configuration, easy to audit and test.
|
|
108
|
+
|
|
109
|
+
### SR-05 — No new dependency without a DECISIONS.md entry
|
|
110
|
+
Adding a package requires justification documented in DECISIONS.md.
|
|
111
|
+
-->
|
|
112
|
+
|
|
113
|
+
[FILL: write your stack-specific rules here, following the SR-NN format above]
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Key Conventions
|
|
118
|
+
|
|
119
|
+
<!--
|
|
120
|
+
Short, scannable list of conventions the agent must respect.
|
|
121
|
+
Examples:
|
|
122
|
+
- Naming: camelCase for variables/functions, PascalCase for classes
|
|
123
|
+
- File naming: kebab-case for files (e.g. user-service.ts)
|
|
124
|
+
- Imports: absolute imports via @ alias (e.g. @/services/user)
|
|
125
|
+
- Date handling: always store UTC, format at display layer
|
|
126
|
+
- IDs: UUID v4 generated by the DB (do not generate in code)
|
|
127
|
+
-->
|
|
128
|
+
|
|
129
|
+
[FILL: list 4–8 conventions that agents must follow when writing code for this project]
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Roles / Access Control
|
|
134
|
+
|
|
135
|
+
<!--
|
|
136
|
+
Describe who can do what. Delete this section if not applicable.
|
|
137
|
+
Example:
|
|
138
|
+
| Role | Permissions |
|
|
139
|
+
|---|---|
|
|
140
|
+
| viewer | read-only access |
|
|
141
|
+
| editor | read + write |
|
|
142
|
+
| admin | full access + user management |
|
|
143
|
+
-->
|
|
144
|
+
|
|
145
|
+
[FILL: describe roles and their permissions, or delete this section]
|
|
@@ -0,0 +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.
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Agents Template — Setup Guide
|
|
2
|
+
|
|
3
|
+
This template implements the **SDD (Spec Driven Development)** workflow using the **RPI (Research → Plan → Implement)** 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 RPI 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 RPI cycle through to implementation
|
|
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 |
|
|
@@ -0,0 +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
|
+
|
|
22
|
+
exit 0
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# guard-deps.sh
|
|
3
|
+
# Asks for confirmation before installing new packages.
|
|
4
|
+
# Reinforces R08: no new dependency without justification in DECISIONS.md.
|
|
5
|
+
# Exit 0 = allow | Exit 2 = block (Claude Code convention)
|
|
6
|
+
|
|
7
|
+
INPUT=$(cat)
|
|
8
|
+
|
|
9
|
+
COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | sed 's/"command":"//;s/"//')
|
|
10
|
+
|
|
11
|
+
# Intercept install commands that add NEW packages (not bare installs like "npm install" with no args)
|
|
12
|
+
if echo "$COMMAND" | grep -qE "^(npm install|npm i|yarn add|pnpm add|bun add) .+" || \
|
|
13
|
+
echo "$COMMAND" | grep -qE "^(pip install|pip3 install|uv add) .+"; then
|
|
14
|
+
echo "⚠️ Agent wants to install a new dependency: $COMMAND" >&2
|
|
15
|
+
echo " Remember: R08 requires justification in DECISIONS.md before adding packages." >&2
|
|
16
|
+
read -r -p "Allow? [y/N] " response < /dev/tty
|
|
17
|
+
if [[ "$response" =~ ^[Yy]$ ]]; then
|
|
18
|
+
exit 0
|
|
19
|
+
else
|
|
20
|
+
echo "Blocked by guard-deps.sh" >&2
|
|
21
|
+
exit 2
|
|
22
|
+
fi
|
|
23
|
+
fi
|
|
24
|
+
|
|
25
|
+
exit 0
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# guard-git.sh
|
|
3
|
+
# Asks for confirmation before running git commit.
|
|
4
|
+
# git push, tag and branch -d are blocked via permissions.deny in settings.json.
|
|
5
|
+
# Exit 0 = allow | Exit 2 = block (Claude Code convention)
|
|
6
|
+
|
|
7
|
+
INPUT=$(cat)
|
|
8
|
+
|
|
9
|
+
# Extract the bash command from the JSON input sent by Claude Code
|
|
10
|
+
COMMAND=$(echo "$INPUT" | grep -o '"command":"[^"]*"' | head -1 | sed 's/"command":"//;s/"//')
|
|
11
|
+
|
|
12
|
+
# Intercept only git commit
|
|
13
|
+
if echo "$COMMAND" | grep -qE "^git commit"; then
|
|
14
|
+
echo "⚠️ Agent wants to run: $COMMAND" >&2
|
|
15
|
+
read -r -p "Allow git commit? [y/N] " response < /dev/tty
|
|
16
|
+
if [[ "$response" =~ ^[Yy]$ ]]; then
|
|
17
|
+
exit 0
|
|
18
|
+
else
|
|
19
|
+
echo "Blocked by guard-git.sh" >&2
|
|
20
|
+
exit 2
|
|
21
|
+
fi
|
|
22
|
+
fi
|
|
23
|
+
|
|
24
|
+
exit 0
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"permissions": {
|
|
3
|
+
"deny": [
|
|
4
|
+
"Bash(git push*)",
|
|
5
|
+
"Bash(git tag*)",
|
|
6
|
+
"Bash(git branch -d*)"
|
|
7
|
+
]
|
|
8
|
+
},
|
|
9
|
+
"hooks": {
|
|
10
|
+
"PreToolUse": [
|
|
11
|
+
{
|
|
12
|
+
"matcher": "Bash",
|
|
13
|
+
"hooks": [{
|
|
14
|
+
"type": "command",
|
|
15
|
+
"command": "bash agents/harness/claude-code/.hooks/guard-git.sh"
|
|
16
|
+
}]
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"matcher": "Bash",
|
|
20
|
+
"hooks": [{
|
|
21
|
+
"type": "command",
|
|
22
|
+
"command": "bash agents/harness/claude-code/.hooks/guard-delete.sh"
|
|
23
|
+
}]
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"matcher": "Bash",
|
|
27
|
+
"hooks": [{
|
|
28
|
+
"type": "command",
|
|
29
|
+
"command": "bash agents/harness/claude-code/.hooks/guard-deps.sh"
|
|
30
|
+
}]
|
|
31
|
+
}
|
|
32
|
+
]
|
|
33
|
+
}
|
|
34
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://opencode.ai/config.json",
|
|
3
|
+
|
|
4
|
+
"instructions": [
|
|
5
|
+
"agents/AGENTS.md",
|
|
6
|
+
"agents/PROJECT.md",
|
|
7
|
+
"agents/RULES.md"
|
|
8
|
+
],
|
|
9
|
+
|
|
10
|
+
"permission": {
|
|
11
|
+
"bash": {
|
|
12
|
+
"git commit *": "deny",
|
|
13
|
+
"git push *": "deny",
|
|
14
|
+
"git tag *": "deny",
|
|
15
|
+
"rm -rf *": "ask"
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
}
|