kodu 1.1.13 → 1.1.15
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/AGENTS.md +184 -199
- package/README.md +32 -3
- package/dist/src/app.module.js +2 -0
- package/dist/src/app.module.js.map +1 -1
- package/dist/src/commands/init/init.command.js +16 -0
- package/dist/src/commands/init/init.command.js.map +1 -1
- package/dist/src/commands/ops/ops.command.d.ts +4 -0
- package/dist/src/commands/ops/ops.command.js +39 -0
- package/dist/src/commands/ops/ops.command.js.map +1 -0
- package/dist/src/commands/ops/ops.module.d.ts +2 -0
- package/dist/src/commands/ops/ops.module.js +33 -0
- package/dist/src/commands/ops/ops.module.js.map +1 -0
- package/dist/src/commands/ops/ops.types.d.ts +13 -0
- package/dist/src/commands/ops/ops.types.js +12 -0
- package/dist/src/commands/ops/ops.types.js.map +1 -0
- package/dist/src/commands/ops/ops.utils.d.ts +13 -0
- package/dist/src/commands/ops/ops.utils.js +117 -0
- package/dist/src/commands/ops/ops.utils.js.map +1 -0
- package/dist/src/commands/ops/subcommands/ops-env.command.d.ts +17 -0
- package/dist/src/commands/ops/subcommands/ops-env.command.js +109 -0
- package/dist/src/commands/ops/subcommands/ops-env.command.js.map +1 -0
- package/dist/src/commands/ops/subcommands/ops-routes.command.d.ts +18 -0
- package/dist/src/commands/ops/subcommands/ops-routes.command.js +166 -0
- package/dist/src/commands/ops/subcommands/ops-routes.command.js.map +1 -0
- package/dist/src/commands/ops/subcommands/ops-service.command.d.ts +16 -0
- package/dist/src/commands/ops/subcommands/ops-service.command.js +128 -0
- package/dist/src/commands/ops/subcommands/ops-service.command.js.map +1 -0
- package/dist/src/commands/ops/subcommands/ops-sysinfo.command.d.ts +9 -0
- package/dist/src/commands/ops/subcommands/ops-sysinfo.command.js +60 -0
- package/dist/src/commands/ops/subcommands/ops-sysinfo.command.js.map +1 -0
- package/dist/src/commands/pack/pack.command.js +1 -2
- package/dist/src/commands/pack/pack.command.js.map +1 -1
- package/dist/src/core/config/config.schema.d.ts +28 -0
- package/dist/src/core/config/config.schema.js +19 -0
- package/dist/src/core/config/config.schema.js.map +1 -1
- package/dist/src/core/file-system/fs.service.d.ts +4 -1
- package/dist/src/core/file-system/fs.service.js +57 -21
- package/dist/src/core/file-system/fs.service.js.map +1 -1
- package/dist/src/shared/constants.d.ts +1 -0
- package/dist/src/shared/constants.js +2 -1
- package/dist/src/shared/constants.js.map +1 -1
- package/dist/src/shared/ssh/ssh.module.d.ts +2 -0
- package/dist/src/shared/ssh/ssh.module.js +21 -0
- package/dist/src/shared/ssh/ssh.module.js.map +1 -0
- package/dist/src/shared/ssh/ssh.service.d.ts +11 -0
- package/dist/src/shared/ssh/ssh.service.js +53 -0
- package/dist/src/shared/ssh/ssh.service.js.map +1 -0
- package/dist/src/shared/tokenizer/tokenizer.service.js +1 -1
- package/dist/src/shared/tokenizer/tokenizer.service.js.map +1 -1
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/docs/plans/2026-03-01-agentops-design.md +194 -0
- package/docs/plans/2026-03-01-agentops-implementation.md +358 -0
- package/kodu.json +15 -0
- package/kodu.schema.json +59 -0
- package/package.json +1 -1
- package/src/app.module.ts +2 -0
- package/src/commands/init/init.command.ts +16 -0
- package/src/commands/ops/ops.command.ts +30 -0
- package/src/commands/ops/ops.module.ts +20 -0
- package/src/commands/ops/ops.types.ts +24 -0
- package/src/commands/ops/ops.utils.ts +156 -0
- package/src/commands/ops/subcommands/ops-env.command.ts +121 -0
- package/src/commands/ops/subcommands/ops-routes.command.ts +185 -0
- package/src/commands/ops/subcommands/ops-service.command.ts +154 -0
- package/src/commands/ops/subcommands/ops-sysinfo.command.ts +53 -0
- package/src/commands/pack/pack.command.ts +1 -2
- package/src/core/config/config.schema.ts +23 -0
- package/src/core/file-system/fs.service.ts +72 -23
- package/src/shared/constants.ts +1 -0
- package/src/shared/ssh/ssh.module.ts +8 -0
- package/src/shared/ssh/ssh.service.ts +61 -0
- package/src/shared/tokenizer/tokenizer.service.ts +2 -2
- package/.cursor/commands/openspec-apply.md +0 -23
- package/.cursor/commands/openspec-archive.md +0 -27
- package/.cursor/commands/openspec-proposal.md +0 -28
- package/.windsurf/workflows/openspec-apply.md +0 -21
- package/.windsurf/workflows/openspec-archive.md +0 -25
- package/.windsurf/workflows/openspec-proposal.md +0 -26
- package/openspec/AGENTS.md +0 -456
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/design.md +0 -30
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/proposal.md +0 -17
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/ai/spec.md +0 -26
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/cleaner/spec.md +0 -26
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/config/spec.md +0 -22
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/ui/spec.md +0 -33
- package/openspec/changes/archive/2026-01-26-translate-project-to-english/tasks.md +0 -33
- package/openspec/project.md +0 -72
- package/openspec/specs/cleaner/spec.md +0 -31
package/openspec/AGENTS.md
DELETED
|
@@ -1,456 +0,0 @@
|
|
|
1
|
-
# OpenSpec Instructions
|
|
2
|
-
|
|
3
|
-
Instructions for AI coding assistants using OpenSpec for spec-driven development.
|
|
4
|
-
|
|
5
|
-
## TL;DR Quick Checklist
|
|
6
|
-
|
|
7
|
-
- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
|
|
8
|
-
- Decide scope: new capability vs modify existing capability
|
|
9
|
-
- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
|
|
10
|
-
- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
|
|
11
|
-
- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
|
|
12
|
-
- Validate: `openspec validate [change-id] --strict --no-interactive` and fix issues
|
|
13
|
-
- Request approval: Do not start implementation until proposal is approved
|
|
14
|
-
|
|
15
|
-
## Three-Stage Workflow
|
|
16
|
-
|
|
17
|
-
### Stage 1: Creating Changes
|
|
18
|
-
Create proposal when you need to:
|
|
19
|
-
- Add features or functionality
|
|
20
|
-
- Make breaking changes (API, schema)
|
|
21
|
-
- Change architecture or patterns
|
|
22
|
-
- Optimize performance (changes behavior)
|
|
23
|
-
- Update security patterns
|
|
24
|
-
|
|
25
|
-
Triggers (examples):
|
|
26
|
-
- "Help me create a change proposal"
|
|
27
|
-
- "Help me plan a change"
|
|
28
|
-
- "Help me create a proposal"
|
|
29
|
-
- "I want to create a spec proposal"
|
|
30
|
-
- "I want to create a spec"
|
|
31
|
-
|
|
32
|
-
Loose matching guidance:
|
|
33
|
-
- Contains one of: `proposal`, `change`, `spec`
|
|
34
|
-
- With one of: `create`, `plan`, `make`, `start`, `help`
|
|
35
|
-
|
|
36
|
-
Skip proposal for:
|
|
37
|
-
- Bug fixes (restore intended behavior)
|
|
38
|
-
- Typos, formatting, comments
|
|
39
|
-
- Dependency updates (non-breaking)
|
|
40
|
-
- Configuration changes
|
|
41
|
-
- Tests for existing behavior
|
|
42
|
-
|
|
43
|
-
**Workflow**
|
|
44
|
-
1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
|
|
45
|
-
2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
|
|
46
|
-
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
|
|
47
|
-
4. Run `openspec validate <id> --strict --no-interactive` and resolve any issues before sharing the proposal.
|
|
48
|
-
|
|
49
|
-
### Stage 2: Implementing Changes
|
|
50
|
-
Track these steps as TODOs and complete them one by one.
|
|
51
|
-
1. **Read proposal.md** - Understand what's being built
|
|
52
|
-
2. **Read design.md** (if exists) - Review technical decisions
|
|
53
|
-
3. **Read tasks.md** - Get implementation checklist
|
|
54
|
-
4. **Implement tasks sequentially** - Complete in order
|
|
55
|
-
5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
|
|
56
|
-
6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
|
|
57
|
-
7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
|
|
58
|
-
|
|
59
|
-
### Stage 3: Archiving Changes
|
|
60
|
-
After deployment, create separate PR to:
|
|
61
|
-
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
|
|
62
|
-
- Update `specs/` if capabilities changed
|
|
63
|
-
- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
|
|
64
|
-
- Run `openspec validate --strict --no-interactive` to confirm the archived change passes checks
|
|
65
|
-
|
|
66
|
-
## Before Any Task
|
|
67
|
-
|
|
68
|
-
**Context Checklist:**
|
|
69
|
-
- [ ] Read relevant specs in `specs/[capability]/spec.md`
|
|
70
|
-
- [ ] Check pending changes in `changes/` for conflicts
|
|
71
|
-
- [ ] Read `openspec/project.md` for conventions
|
|
72
|
-
- [ ] Run `openspec list` to see active changes
|
|
73
|
-
- [ ] Run `openspec list --specs` to see existing capabilities
|
|
74
|
-
|
|
75
|
-
**Before Creating Specs:**
|
|
76
|
-
- Always check if capability already exists
|
|
77
|
-
- Prefer modifying existing specs over creating duplicates
|
|
78
|
-
- Use `openspec show [spec]` to review current state
|
|
79
|
-
- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
|
|
80
|
-
|
|
81
|
-
### Search Guidance
|
|
82
|
-
- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
|
|
83
|
-
- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
|
|
84
|
-
- Show details:
|
|
85
|
-
- Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
|
|
86
|
-
- Change: `openspec show <change-id> --json --deltas-only`
|
|
87
|
-
- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
|
|
88
|
-
|
|
89
|
-
## Quick Start
|
|
90
|
-
|
|
91
|
-
### CLI Commands
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
# Essential commands
|
|
95
|
-
openspec list # List active changes
|
|
96
|
-
openspec list --specs # List specifications
|
|
97
|
-
openspec show [item] # Display change or spec
|
|
98
|
-
openspec validate [item] # Validate changes or specs
|
|
99
|
-
openspec archive <change-id> [--yes|-y] # Archive after deployment (add --yes for non-interactive runs)
|
|
100
|
-
|
|
101
|
-
# Project management
|
|
102
|
-
openspec init [path] # Initialize OpenSpec
|
|
103
|
-
openspec update [path] # Update instruction files
|
|
104
|
-
|
|
105
|
-
# Interactive mode
|
|
106
|
-
openspec show # Prompts for selection
|
|
107
|
-
openspec validate # Bulk validation mode
|
|
108
|
-
|
|
109
|
-
# Debugging
|
|
110
|
-
openspec show [change] --json --deltas-only
|
|
111
|
-
openspec validate [change] --strict --no-interactive
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
### Command Flags
|
|
115
|
-
|
|
116
|
-
- `--json` - Machine-readable output
|
|
117
|
-
- `--type change|spec` - Disambiguate items
|
|
118
|
-
- `--strict` - Comprehensive validation
|
|
119
|
-
- `--no-interactive` - Disable prompts
|
|
120
|
-
- `--skip-specs` - Archive without spec updates
|
|
121
|
-
- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
|
|
122
|
-
|
|
123
|
-
## Directory Structure
|
|
124
|
-
|
|
125
|
-
```
|
|
126
|
-
openspec/
|
|
127
|
-
├── project.md # Project conventions
|
|
128
|
-
├── specs/ # Current truth - what IS built
|
|
129
|
-
│ └── [capability]/ # Single focused capability
|
|
130
|
-
│ ├── spec.md # Requirements and scenarios
|
|
131
|
-
│ └── design.md # Technical patterns
|
|
132
|
-
├── changes/ # Proposals - what SHOULD change
|
|
133
|
-
│ ├── [change-name]/
|
|
134
|
-
│ │ ├── proposal.md # Why, what, impact
|
|
135
|
-
│ │ ├── tasks.md # Implementation checklist
|
|
136
|
-
│ │ ├── design.md # Technical decisions (optional; see criteria)
|
|
137
|
-
│ │ └── specs/ # Delta changes
|
|
138
|
-
│ │ └── [capability]/
|
|
139
|
-
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
|
|
140
|
-
│ └── archive/ # Completed changes
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
## Creating Change Proposals
|
|
144
|
-
|
|
145
|
-
### Decision Tree
|
|
146
|
-
|
|
147
|
-
```
|
|
148
|
-
New request?
|
|
149
|
-
├─ Bug fix restoring spec behavior? → Fix directly
|
|
150
|
-
├─ Typo/format/comment? → Fix directly
|
|
151
|
-
├─ New feature/capability? → Create proposal
|
|
152
|
-
├─ Breaking change? → Create proposal
|
|
153
|
-
├─ Architecture change? → Create proposal
|
|
154
|
-
└─ Unclear? → Create proposal (safer)
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
### Proposal Structure
|
|
158
|
-
|
|
159
|
-
1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
|
|
160
|
-
|
|
161
|
-
2. **Write proposal.md:**
|
|
162
|
-
```markdown
|
|
163
|
-
# Change: [Brief description of change]
|
|
164
|
-
|
|
165
|
-
## Why
|
|
166
|
-
[1-2 sentences on problem/opportunity]
|
|
167
|
-
|
|
168
|
-
## What Changes
|
|
169
|
-
- [Bullet list of changes]
|
|
170
|
-
- [Mark breaking changes with **BREAKING**]
|
|
171
|
-
|
|
172
|
-
## Impact
|
|
173
|
-
- Affected specs: [list capabilities]
|
|
174
|
-
- Affected code: [key files/systems]
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
3. **Create spec deltas:** `specs/[capability]/spec.md`
|
|
178
|
-
```markdown
|
|
179
|
-
## ADDED Requirements
|
|
180
|
-
### Requirement: New Feature
|
|
181
|
-
The system SHALL provide...
|
|
182
|
-
|
|
183
|
-
#### Scenario: Success case
|
|
184
|
-
- **WHEN** user performs action
|
|
185
|
-
- **THEN** expected result
|
|
186
|
-
|
|
187
|
-
## MODIFIED Requirements
|
|
188
|
-
### Requirement: Existing Feature
|
|
189
|
-
[Complete modified requirement]
|
|
190
|
-
|
|
191
|
-
## REMOVED Requirements
|
|
192
|
-
### Requirement: Old Feature
|
|
193
|
-
**Reason**: [Why removing]
|
|
194
|
-
**Migration**: [How to handle]
|
|
195
|
-
```
|
|
196
|
-
If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
|
|
197
|
-
|
|
198
|
-
4. **Create tasks.md:**
|
|
199
|
-
```markdown
|
|
200
|
-
## 1. Implementation
|
|
201
|
-
- [ ] 1.1 Create database schema
|
|
202
|
-
- [ ] 1.2 Implement API endpoint
|
|
203
|
-
- [ ] 1.3 Add frontend component
|
|
204
|
-
- [ ] 1.4 Write tests
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
5. **Create design.md when needed:**
|
|
208
|
-
Create `design.md` if any of the following apply; otherwise omit it:
|
|
209
|
-
- Cross-cutting change (multiple services/modules) or a new architectural pattern
|
|
210
|
-
- New external dependency or significant data model changes
|
|
211
|
-
- Security, performance, or migration complexity
|
|
212
|
-
- Ambiguity that benefits from technical decisions before coding
|
|
213
|
-
|
|
214
|
-
Minimal `design.md` skeleton:
|
|
215
|
-
```markdown
|
|
216
|
-
## Context
|
|
217
|
-
[Background, constraints, stakeholders]
|
|
218
|
-
|
|
219
|
-
## Goals / Non-Goals
|
|
220
|
-
- Goals: [...]
|
|
221
|
-
- Non-Goals: [...]
|
|
222
|
-
|
|
223
|
-
## Decisions
|
|
224
|
-
- Decision: [What and why]
|
|
225
|
-
- Alternatives considered: [Options + rationale]
|
|
226
|
-
|
|
227
|
-
## Risks / Trade-offs
|
|
228
|
-
- [Risk] → Mitigation
|
|
229
|
-
|
|
230
|
-
## Migration Plan
|
|
231
|
-
[Steps, rollback]
|
|
232
|
-
|
|
233
|
-
## Open Questions
|
|
234
|
-
- [...]
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
## Spec File Format
|
|
238
|
-
|
|
239
|
-
### Critical: Scenario Formatting
|
|
240
|
-
|
|
241
|
-
**CORRECT** (use #### headers):
|
|
242
|
-
```markdown
|
|
243
|
-
#### Scenario: User login success
|
|
244
|
-
- **WHEN** valid credentials provided
|
|
245
|
-
- **THEN** return JWT token
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
**WRONG** (don't use bullets or bold):
|
|
249
|
-
```markdown
|
|
250
|
-
- **Scenario: User login** ❌
|
|
251
|
-
**Scenario**: User login ❌
|
|
252
|
-
### Scenario: User login ❌
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
Every requirement MUST have at least one scenario.
|
|
256
|
-
|
|
257
|
-
### Requirement Wording
|
|
258
|
-
- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
|
|
259
|
-
|
|
260
|
-
### Delta Operations
|
|
261
|
-
|
|
262
|
-
- `## ADDED Requirements` - New capabilities
|
|
263
|
-
- `## MODIFIED Requirements` - Changed behavior
|
|
264
|
-
- `## REMOVED Requirements` - Deprecated features
|
|
265
|
-
- `## RENAMED Requirements` - Name changes
|
|
266
|
-
|
|
267
|
-
Headers matched with `trim(header)` - whitespace ignored.
|
|
268
|
-
|
|
269
|
-
#### When to use ADDED vs MODIFIED
|
|
270
|
-
- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
|
|
271
|
-
- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
|
|
272
|
-
- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
|
|
273
|
-
|
|
274
|
-
Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
|
|
275
|
-
|
|
276
|
-
Authoring a MODIFIED requirement correctly:
|
|
277
|
-
1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
|
|
278
|
-
2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
|
|
279
|
-
3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
|
|
280
|
-
4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
|
|
281
|
-
|
|
282
|
-
Example for RENAMED:
|
|
283
|
-
```markdown
|
|
284
|
-
## RENAMED Requirements
|
|
285
|
-
- FROM: `### Requirement: Login`
|
|
286
|
-
- TO: `### Requirement: User Authentication`
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
## Troubleshooting
|
|
290
|
-
|
|
291
|
-
### Common Errors
|
|
292
|
-
|
|
293
|
-
**"Change must have at least one delta"**
|
|
294
|
-
- Check `changes/[name]/specs/` exists with .md files
|
|
295
|
-
- Verify files have operation prefixes (## ADDED Requirements)
|
|
296
|
-
|
|
297
|
-
**"Requirement must have at least one scenario"**
|
|
298
|
-
- Check scenarios use `#### Scenario:` format (4 hashtags)
|
|
299
|
-
- Don't use bullet points or bold for scenario headers
|
|
300
|
-
|
|
301
|
-
**Silent scenario parsing failures**
|
|
302
|
-
- Exact format required: `#### Scenario: Name`
|
|
303
|
-
- Debug with: `openspec show [change] --json --deltas-only`
|
|
304
|
-
|
|
305
|
-
### Validation Tips
|
|
306
|
-
|
|
307
|
-
```bash
|
|
308
|
-
# Always use strict mode for comprehensive checks
|
|
309
|
-
openspec validate [change] --strict --no-interactive
|
|
310
|
-
|
|
311
|
-
# Debug delta parsing
|
|
312
|
-
openspec show [change] --json | jq '.deltas'
|
|
313
|
-
|
|
314
|
-
# Check specific requirement
|
|
315
|
-
openspec show [spec] --json -r 1
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
## Happy Path Script
|
|
319
|
-
|
|
320
|
-
```bash
|
|
321
|
-
# 1) Explore current state
|
|
322
|
-
openspec spec list --long
|
|
323
|
-
openspec list
|
|
324
|
-
# Optional full-text search:
|
|
325
|
-
# rg -n "Requirement:|Scenario:" openspec/specs
|
|
326
|
-
# rg -n "^#|Requirement:" openspec/changes
|
|
327
|
-
|
|
328
|
-
# 2) Choose change id and scaffold
|
|
329
|
-
CHANGE=add-two-factor-auth
|
|
330
|
-
mkdir -p openspec/changes/$CHANGE/{specs/auth}
|
|
331
|
-
printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
|
|
332
|
-
printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
|
|
333
|
-
|
|
334
|
-
# 3) Add deltas (example)
|
|
335
|
-
cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
|
|
336
|
-
## ADDED Requirements
|
|
337
|
-
### Requirement: Two-Factor Authentication
|
|
338
|
-
Users MUST provide a second factor during login.
|
|
339
|
-
|
|
340
|
-
#### Scenario: OTP required
|
|
341
|
-
- **WHEN** valid credentials are provided
|
|
342
|
-
- **THEN** an OTP challenge is required
|
|
343
|
-
EOF
|
|
344
|
-
|
|
345
|
-
# 4) Validate
|
|
346
|
-
openspec validate $CHANGE --strict --no-interactive
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
## Multi-Capability Example
|
|
350
|
-
|
|
351
|
-
```
|
|
352
|
-
openspec/changes/add-2fa-notify/
|
|
353
|
-
├── proposal.md
|
|
354
|
-
├── tasks.md
|
|
355
|
-
└── specs/
|
|
356
|
-
├── auth/
|
|
357
|
-
│ └── spec.md # ADDED: Two-Factor Authentication
|
|
358
|
-
└── notifications/
|
|
359
|
-
└── spec.md # ADDED: OTP email notification
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
auth/spec.md
|
|
363
|
-
```markdown
|
|
364
|
-
## ADDED Requirements
|
|
365
|
-
### Requirement: Two-Factor Authentication
|
|
366
|
-
...
|
|
367
|
-
```
|
|
368
|
-
|
|
369
|
-
notifications/spec.md
|
|
370
|
-
```markdown
|
|
371
|
-
## ADDED Requirements
|
|
372
|
-
### Requirement: OTP Email Notification
|
|
373
|
-
...
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
## Best Practices
|
|
377
|
-
|
|
378
|
-
### Simplicity First
|
|
379
|
-
- Default to <100 lines of new code
|
|
380
|
-
- Single-file implementations until proven insufficient
|
|
381
|
-
- Avoid frameworks without clear justification
|
|
382
|
-
- Choose boring, proven patterns
|
|
383
|
-
|
|
384
|
-
### Complexity Triggers
|
|
385
|
-
Only add complexity with:
|
|
386
|
-
- Performance data showing current solution too slow
|
|
387
|
-
- Concrete scale requirements (>1000 users, >100MB data)
|
|
388
|
-
- Multiple proven use cases requiring abstraction
|
|
389
|
-
|
|
390
|
-
### Clear References
|
|
391
|
-
- Use `file.ts:42` format for code locations
|
|
392
|
-
- Reference specs as `specs/auth/spec.md`
|
|
393
|
-
- Link related changes and PRs
|
|
394
|
-
|
|
395
|
-
### Capability Naming
|
|
396
|
-
- Use verb-noun: `user-auth`, `payment-capture`
|
|
397
|
-
- Single purpose per capability
|
|
398
|
-
- 10-minute understandability rule
|
|
399
|
-
- Split if description needs "AND"
|
|
400
|
-
|
|
401
|
-
### Change ID Naming
|
|
402
|
-
- Use kebab-case, short and descriptive: `add-two-factor-auth`
|
|
403
|
-
- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
|
|
404
|
-
- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
|
|
405
|
-
|
|
406
|
-
## Tool Selection Guide
|
|
407
|
-
|
|
408
|
-
| Task | Tool | Why |
|
|
409
|
-
|------|------|-----|
|
|
410
|
-
| Find files by pattern | Glob | Fast pattern matching |
|
|
411
|
-
| Search code content | Grep | Optimized regex search |
|
|
412
|
-
| Read specific files | Read | Direct file access |
|
|
413
|
-
| Explore unknown scope | Task | Multi-step investigation |
|
|
414
|
-
|
|
415
|
-
## Error Recovery
|
|
416
|
-
|
|
417
|
-
### Change Conflicts
|
|
418
|
-
1. Run `openspec list` to see active changes
|
|
419
|
-
2. Check for overlapping specs
|
|
420
|
-
3. Coordinate with change owners
|
|
421
|
-
4. Consider combining proposals
|
|
422
|
-
|
|
423
|
-
### Validation Failures
|
|
424
|
-
1. Run with `--strict` flag
|
|
425
|
-
2. Check JSON output for details
|
|
426
|
-
3. Verify spec file format
|
|
427
|
-
4. Ensure scenarios properly formatted
|
|
428
|
-
|
|
429
|
-
### Missing Context
|
|
430
|
-
1. Read project.md first
|
|
431
|
-
2. Check related specs
|
|
432
|
-
3. Review recent archives
|
|
433
|
-
4. Ask for clarification
|
|
434
|
-
|
|
435
|
-
## Quick Reference
|
|
436
|
-
|
|
437
|
-
### Stage Indicators
|
|
438
|
-
- `changes/` - Proposed, not yet built
|
|
439
|
-
- `specs/` - Built and deployed
|
|
440
|
-
- `archive/` - Completed changes
|
|
441
|
-
|
|
442
|
-
### File Purposes
|
|
443
|
-
- `proposal.md` - Why and what
|
|
444
|
-
- `tasks.md` - Implementation steps
|
|
445
|
-
- `design.md` - Technical decisions
|
|
446
|
-
- `spec.md` - Requirements and behavior
|
|
447
|
-
|
|
448
|
-
### CLI Essentials
|
|
449
|
-
```bash
|
|
450
|
-
openspec list # What's in progress?
|
|
451
|
-
openspec show [item] # View details
|
|
452
|
-
openspec validate --strict --no-interactive # Is it correct?
|
|
453
|
-
openspec archive <change-id> [--yes|-y] # Mark complete (add --yes for automation)
|
|
454
|
-
```
|
|
455
|
-
|
|
456
|
-
Remember: Specs are truth. Changes are proposals. Keep them in sync.
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
## Context
|
|
2
|
-
The Kodu CLI project currently uses mixed languages with Russian prompts and error messages. This creates inconsistency and limits international adoption. The project needs comprehensive translation to English while maintaining functionality.
|
|
3
|
-
|
|
4
|
-
## Goals / Non-Goals
|
|
5
|
-
- Goals: Complete translation of all user-facing text to English
|
|
6
|
-
- Goals: Maintain all existing functionality
|
|
7
|
-
- Goals: Ensure consistency across all prompts and messages
|
|
8
|
-
- Non-Goals: Translate code comments (keep technical comments)
|
|
9
|
-
- Non-Goals: Change project structure or architecture
|
|
10
|
-
|
|
11
|
-
## Decisions
|
|
12
|
-
- Decision: Translate all user-facing strings to English
|
|
13
|
-
- Decision: Keep technical code comments in original form for developer context
|
|
14
|
-
- Decision: Maintain existing prompt structure and variable substitution
|
|
15
|
-
- Alternatives considered: Keep bilingual support (rejected for complexity)
|
|
16
|
-
|
|
17
|
-
## Risks / Trade-offs
|
|
18
|
-
- Breaking change for existing Russian-speaking users
|
|
19
|
-
- Risk of translation errors affecting prompt quality
|
|
20
|
-
- Trade-off: Better international adoption vs current user base disruption
|
|
21
|
-
|
|
22
|
-
## Migration Plan
|
|
23
|
-
- Translate all files systematically
|
|
24
|
-
- Test each command individually
|
|
25
|
-
- Update documentation
|
|
26
|
-
- Release with migration guide
|
|
27
|
-
|
|
28
|
-
## Open Questions
|
|
29
|
-
- How to handle existing Russian user configurations?
|
|
30
|
-
- Should we provide fallback support for Russian prompts?
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
# Change: Translate all project content from Russian to English
|
|
2
|
-
|
|
3
|
-
## Why
|
|
4
|
-
The project currently contains mixed language content with Russian text in prompts, error messages, specifications, and user-facing strings. This creates inconsistency and limits the project's accessibility to international contributors and users.
|
|
5
|
-
|
|
6
|
-
## What Changes
|
|
7
|
-
- Translate all Russian prompts in `src/core/config/default-prompts.ts`
|
|
8
|
-
- Translate all Russian prompt templates in `.kodu/prompts/` directory
|
|
9
|
-
- Translate Russian specifications in `openspec/specs/cleaner/spec.md`
|
|
10
|
-
- Translate Russian error messages and user-facing strings in command files
|
|
11
|
-
- Update all Russian comments and documentation to English
|
|
12
|
-
- **BREAKING**: Changes all user-facing text from Russian to English
|
|
13
|
-
|
|
14
|
-
## Impact
|
|
15
|
-
- Affected specs: cleaner, ai, config, ui
|
|
16
|
-
- Affected code: All command files, configuration services, prompt templates
|
|
17
|
-
- User experience: All CLI output and prompts will be in English
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
## ADDED Requirements
|
|
2
|
-
### Requirement: English Review Prompts
|
|
3
|
-
The AI service SHALL provide English-language review prompts for bug, style, and security analysis modes.
|
|
4
|
-
|
|
5
|
-
#### Scenario: Bug review in English
|
|
6
|
-
- **WHEN** `kodu review --mode bug` is executed
|
|
7
|
-
- **THEN** the AI receives an English prompt asking it to act as a strict code reviewer and find potential bugs, logical errors, and regressions
|
|
8
|
-
|
|
9
|
-
#### Scenario: Style review in English
|
|
10
|
-
- **WHEN** `kodu review --mode style` is executed
|
|
11
|
-
- **THEN** the AI receives an English prompt asking it to check readability, consistency, formatting, and naming
|
|
12
|
-
|
|
13
|
-
#### Scenario: Security review in English
|
|
14
|
-
- **WHEN** `kodu review --mode security` is executed
|
|
15
|
-
- **THEN** the AI receives an English prompt asking it to find vulnerabilities, secret leaks, and improper permission checks
|
|
16
|
-
|
|
17
|
-
### Requirement: English Error Messages
|
|
18
|
-
The AI service SHALL provide English error messages for API key validation and model configuration.
|
|
19
|
-
|
|
20
|
-
#### Scenario: Missing API key in English
|
|
21
|
-
- **WHEN** AI command is executed without API key
|
|
22
|
-
- **THEN** the system displays English error message about missing API key and setup instructions
|
|
23
|
-
|
|
24
|
-
#### Scenario: Invalid model format in English
|
|
25
|
-
- **WHEN** model configuration is invalid
|
|
26
|
-
- **THEN** the system displays English error message about expected model format
|
package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/cleaner/spec.md
DELETED
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
## MODIFIED Requirements
|
|
2
|
-
### Requirement: Comment Recognition
|
|
3
|
-
The `clean` command SHALL detect and remove any form of comments in files (`//`, `/* ... */`, HTML `<!-- ... -->`, etc.), except for constructs covered by `keepJSDoc` or custom/system whitelist. HTML `<!-- ... -->` should only be removed in `.html`/`.htm` files, so that lines with similar regular expressions or literals in TypeScript/JavaScript remain untouched. Removal SHALL occur without distorting surrounding code and be reflected in `--dry-run` previews.
|
|
4
|
-
|
|
5
|
-
#### Scenario: Remove multi-line `/* ... */` blocks
|
|
6
|
-
- **WHEN** `kodu clean` runs on a TS/JS file containing a `/* ... */` block that is not marked as JSDoc or not in the whitelist
|
|
7
|
-
- **THEN** the block is removed, surrounding code remains syntactically correct, and `--dry-run` shows this range without applying changes
|
|
8
|
-
|
|
9
|
-
#### Scenario: Remove HTML comments inside templates
|
|
10
|
-
- **WHEN** `kodu clean` runs on a template file (`.html` or `.htm`) with comments of the form `<!-- ... -->`
|
|
11
|
-
- **THEN** HTML comments are removed, template structure is preserved, and output/generation does not contain extra whitespace lines
|
|
12
|
-
|
|
13
|
-
#### Scenario: HTML comment in TypeScript literal remains untouched
|
|
14
|
-
- **WHEN** `kodu clean` runs on a TS/JS file where a pattern `` `<!--[\s\S]*?-->` `` appears inside a string or regular expression
|
|
15
|
-
- **THEN** the text remains unchanged because HTML parsing is limited to `.html`/`.htm` files only
|
|
16
|
-
|
|
17
|
-
### Requirement: Clean Only Changed Files
|
|
18
|
-
The `clean` command SHALL accept a `--changed` flag (short form `-c`) that switches the operation to process only those files where Git has detected changes. Extension rules continue to apply, and output is lost if no files match the filter. Switching to `--dry-run` remains possible, it only changes the message without actual writing.
|
|
19
|
-
|
|
20
|
-
#### Scenario: Clean changes in `--changed` mode
|
|
21
|
-
- **WHEN** `kodu clean --changed` runs in a repository with changed TypeScript/HTML files
|
|
22
|
-
- **THEN** the command removes comments only from changed files, others are skipped, and the count of affected files/comments reflects only this selection
|
|
23
|
-
|
|
24
|
-
#### Scenario: `--changed` mode with no current files
|
|
25
|
-
- **WHEN** `kodu clean --changed` runs but Git produces no changed file with suitable extension
|
|
26
|
-
- **THEN** the command makes no changes and outputs warning `No changed files to clean.`, and the spinner stops without executing `cleaner.cleanFiles`
|
package/openspec/changes/archive/2026-01-26-translate-project-to-english/specs/config/spec.md
DELETED
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
## MODIFIED Requirements
|
|
2
|
-
### Requirement: English Configuration Validation
|
|
3
|
-
The configuration service SHALL provide English error messages for missing or invalid configuration files.
|
|
4
|
-
|
|
5
|
-
#### Scenario: Missing configuration file in English
|
|
6
|
-
- **WHEN** `kodu.json` is not found
|
|
7
|
-
- **THEN** the system displays English error message suggesting to run `kodu init`
|
|
8
|
-
|
|
9
|
-
#### Scenario: Invalid configuration in English
|
|
10
|
-
- **WHEN** `kodu.json` contains validation errors
|
|
11
|
-
- **THEN** the system displays English error messages for each validation issue
|
|
12
|
-
|
|
13
|
-
### Requirement: English Prompt Loading
|
|
14
|
-
The prompt service SHALL provide English error messages for missing or invalid prompt templates.
|
|
15
|
-
|
|
16
|
-
#### Scenario: Missing prompt template in English
|
|
17
|
-
- **WHEN** a prompt template file is not found
|
|
18
|
-
- **THEN** the system displays English error message with expected file paths
|
|
19
|
-
|
|
20
|
-
#### Scenario: Invalid prompt file in English
|
|
21
|
-
- **WHEN** a prompt file path is invalid
|
|
22
|
-
- **THEN** the system displays English error message about file not found
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
## ADDED Requirements
|
|
2
|
-
### Requirement: English CLI Commands
|
|
3
|
-
All CLI commands SHALL provide English descriptions, option help text, and user-facing messages.
|
|
4
|
-
|
|
5
|
-
#### Scenario: English command descriptions
|
|
6
|
-
- **WHEN** users run `kodu --help` or command-specific help
|
|
7
|
-
- **THEN** all command descriptions and option help text are in English
|
|
8
|
-
|
|
9
|
-
#### Scenario: English command output
|
|
10
|
-
- **WHEN** users execute any kodu command
|
|
11
|
-
- **THEN** all progress messages, spinners, and results are in English
|
|
12
|
-
|
|
13
|
-
### Requirement: English Error Handling
|
|
14
|
-
All error messages and warnings SHALL be displayed in English.
|
|
15
|
-
|
|
16
|
-
#### Scenario: English error messages
|
|
17
|
-
- **WHEN** an error occurs during command execution
|
|
18
|
-
- **THEN** the error message is in English with clear guidance
|
|
19
|
-
|
|
20
|
-
#### Scenario: English warning messages
|
|
21
|
-
- **WHEN** a warning is displayed (e.g., missing staged changes)
|
|
22
|
-
- **THEN** the warning message is in English
|
|
23
|
-
|
|
24
|
-
### Requirement: English Interactive Prompts
|
|
25
|
-
All interactive prompts and user dialogs SHALL be in English.
|
|
26
|
-
|
|
27
|
-
#### Scenario: English confirmation prompts
|
|
28
|
-
- **WHEN** a command requires user confirmation
|
|
29
|
-
- **THEN** the prompt text is in English
|
|
30
|
-
|
|
31
|
-
#### Scenario: English input prompts
|
|
32
|
-
- **WHEN** a command requires user input
|
|
33
|
-
- **THEN** the prompt text and validation messages are in English
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
## 1. Translation Preparation
|
|
2
|
-
- [x] 1.1 Inventory all Russian text in the codebase
|
|
3
|
-
- [x] 1.2 Create translation mapping for key terms
|
|
4
|
-
- [x] 1.3 Identify user-facing vs internal strings
|
|
5
|
-
|
|
6
|
-
## 2. Core Configuration Translation
|
|
7
|
-
- [x] 2.1 Translate `DEFAULT_REVIEW_PROMPTS` in `src/core/config/default-prompts.ts`
|
|
8
|
-
- [x] 2.2 Translate prompt templates in `.kodu/prompts/` directory
|
|
9
|
-
- [x] 2.3 Update configuration schema if needed
|
|
10
|
-
|
|
11
|
-
## 3. Command Files Translation
|
|
12
|
-
- [x] 3.1 Translate Russian strings in `src/commands/review/review.command.ts`
|
|
13
|
-
- [x] 3.2 Translate Russian strings in `src/commands/commit/commit.command.ts`
|
|
14
|
-
- [x] 3.3 Translate Russian strings in `src/commands/init/init.command.ts`
|
|
15
|
-
- [x] 3.4 Translate Russian strings in `src/commands/pack/pack.command.ts`
|
|
16
|
-
- [x] 3.5 Translate Russian strings in `src/commands/clean/clean.command.ts`
|
|
17
|
-
|
|
18
|
-
## 4. Service Files Translation
|
|
19
|
-
- [x] 4.1 Translate Russian strings in `src/shared/ai/ai.service.ts`
|
|
20
|
-
- [x] 4.2 Translate Russian strings in `src/core/config/config.service.ts`
|
|
21
|
-
- [x] 4.3 Translate Russian strings in `src/core/config/prompt.service.ts`
|
|
22
|
-
- [x] 4.4 Translate Russian strings in `src/shared/git/git.service.ts`
|
|
23
|
-
|
|
24
|
-
## 5. Documentation Translation
|
|
25
|
-
- [x] 5.1 Translate `openspec/specs/cleaner/spec.md`
|
|
26
|
-
- [x] 5.2 Update archived changes documentation
|
|
27
|
-
- [x] 5.3 Translate `docs/todo.md`
|
|
28
|
-
- [x] 5.4 Update Russian examples in `AGENTS.md`
|
|
29
|
-
|
|
30
|
-
## 6. Validation
|
|
31
|
-
- [x] 6.1 Test all commands with English output
|
|
32
|
-
- [x] 6.2 Verify no Russian text remains in user-facing strings
|
|
33
|
-
- [x] 6.3 Run `npm run check` to ensure no breaking changes
|