feat: initial commit - opencode spec-driven development boilerplate

Converted from Claude Code boilerplate to opencode:
- CLAUDE.md -> AGENTS.md (opencode instructions)
- .claude/settings.json -> opencode.json (permissions schema)
- .claude/agents/ -> .opencode/agent/ (subagents with mode: subagent)
- .claude/commands/ -> .opencode/command/ (slash commands with )
- .claude/skills/ -> .opencode/skills/ (7 skills, removed allowed-tools)
- DevContainer updated to install opencode
- All .claude/ paths and Claude Code references updated
This commit is contained in:
2026-06-24 22:32:45 +02:00
commit ced279e2df
45 changed files with 7439 additions and 0 deletions

View File

@ -0,0 +1,51 @@
---
name: repository-structure
description: A detailed guide and template for creating a repository structure definition document. Use only when defining the repository structure.
---
# Repository Structure Definition Skill
This skill is a detailed guide for defining a clear and maintainable repository structure.
## Prerequisites
Before you begin defining the repository structure, confirm the following:
### Required documents
1. `docs/product-requirements.md` (PRD)
2. `docs/functional-design.md` (Functional Design Document)
3. `docs/architecture.md` (Architecture Design Document)
The repository structure defines a concrete directory layout that reflects the technology stack and system composition determined during architecture design.
## Priority of existing documents
**Important**: If an existing repository structure definition document is present at `docs/repository-structure.md`, follow the priority order below:
1. **Existing repository structure definition document (`docs/repository-structure.md`)** - Highest priority
- Contains the project-specific directory structure
- Takes precedence over this skill's guide
2. **This skill's guide** - Reference material
- Generic templates and examples
- Use when there is no existing definition document, or as a supplement
**When creating from scratch**: Refer to this skill's template and guide
**When updating**: Update while preserving the structure and content of the existing definition document
## Output destination
Save the repository structure definition document you create to the following location:
```
docs/repository-structure.md
```
## Template reference
When creating the repository structure definition document, use the following template: ./template.md
## Detailed guide
For a more detailed creation guide, refer to the following file: ./guide.md

View File

@ -0,0 +1,400 @@
# Repository Structure Document Authoring Guide
## Basic Principles
### 1. Clarify Roles
Each directory should have a single, well-defined role.
**Bad example**:
```
src/
├── stuff/ # Vague
├── misc/ # Miscellaneous
└── utils/ # Too generic
```
**Good example**:
```
src/
├── commands/ # CLI command implementations
├── services/ # Business logic
├── repositories/ # Data persistence
└── validators/ # Input validation
```
### 2. Enforce Layer Separation
Reflect the architecture's layer structure in the directory structure:
```
src/
├── ui/ # UI layer
│ └── cli/ # CLI implementation
├── services/ # Service layer
│ └── task/ # Task management service
└── repositories/ # Data layer
└── task/ # Task repository
```
### 3. Split by Technical Concern (Baseline)
Split directories by related technical concerns:
**Basic structure**:
```
src/
├── commands/ # CLI commands
├── services/ # Business logic
├── repositories/ # Data persistence
└── types/ # Type definitions
```
**Mapping to the layer structure**:
```
CLI/UI layer → commands/, cli/
Service layer → services/
Data layer → repositories/, storage/
```
## Designing the Directory Structure
### Expressing the Layer Structure
```typescript
// Bad example: flat structure
src/
├── TaskCLI.ts
├── TaskService.ts
├── TaskRepository.ts
├── UserCLI.ts
├── UserService.ts
└── UserRepository.ts
// Good example: clear layers
src/
├── cli/
├── TaskCLI.ts
└── UserCLI.ts
├── services/
├── TaskService.ts
└── UserService.ts
└── repositories/
├── TaskRepository.ts
└── UserRepository.ts
```
### Placement of the Test Directory
**Recommended structure**:
```
project/
├── src/
│ └── services/
│ └── TaskService.ts
└── tests/
├── unit/
│ └── services/
│ └── TaskService.test.ts
├── integration/
└── e2e/
```
**Rationale**:
- Test code is separated from production code
- Easy to exclude tests at build time
- Can be organized by test type
## Naming Convention Best Practices
### Principles for Directory Names
**1. Use the plural form (layer directories)**
```
✅ services/
✅ repositories/
✅ controllers/
❌ service/
❌ repository/
❌ controller/
```
Rationale: They hold multiple files
**2. Use kebab-case**
```
✅ task-management/
✅ user-authentication/
❌ TaskManagement/
❌ userAuthentication/
```
Rationale: Compatibility with URLs and the file system
**3. Use specific names**
```
✅ validators/ # Input validation
✅ formatters/ # Data formatting
✅ parsers/ # Data parsing
❌ utils/ # Too generic
❌ helpers/ # Vague
❌ common/ # Meaningless
```
### Principles for File Names
**1. Class files: PascalCase + role suffix**
```typescript
// Service classes
TaskService.ts
UserAuthenticationService.ts
// Repository classes
TaskRepository.ts
UserRepository.ts
// Controller classes
TaskController.ts
```
**2. Function files: camelCase + start with a verb**
```typescript
// Utility functions
formatDate.ts
validateEmail.ts
parseCommandArguments.ts
```
**3. Type definition files: PascalCase or kebab-case**
```typescript
// Interface definitions
Task.ts
UserProfile.ts
// Type definition collections
task-types.d.ts
api-types.d.ts
```
**4. Constant files: UPPER_SNAKE_CASE or kebab-case**
```typescript
// Constant definitions
API_ENDPOINTS.ts
ERROR_MESSAGES.ts
// or
api-endpoints.ts
error-messages.ts
```
## Managing Dependencies
### Dependency Rules Between Layers
```typescript
// ✅ Good example: dependency from an upper layer to a lower layer
// cli/TaskCLI.ts
import { TaskService } from '../services/TaskService';
class TaskCLI {
constructor(private taskService: TaskService) {}
}
// ❌ Bad example: dependency from a lower layer to an upper layer
// services/TaskService.ts
import { TaskCLI } from '../cli/TaskCLI'; // Forbidden!
```
### Avoiding Circular Dependencies
**Problematic code**:
```typescript
// services/TaskService.ts
import { UserService } from './UserService';
export class TaskService {
constructor(private userService: UserService) {}
}
// services/UserService.ts
import { TaskService } from './TaskService'; // Circular dependency!
export class UserService {
constructor(private taskService: TaskService) {}
}
```
**Solution 1: Extract shared type definitions**
```typescript
// types/Service.ts
export interface ITaskService { /* ... */ }
export interface IUserService { /* ... */ }
// services/TaskService.ts
import type { IUserService } from '../types/Service';
export class TaskService {
constructor(private userService: IUserService) {}
}
// services/UserService.ts
import type { ITaskService } from '../types/Service';
export class UserService {
constructor(private taskService: ITaskService) {}
}
```
**Solution 2: Rethink the dependencies**
```typescript
// Extract shared functionality into a separate service
// services/NotificationService.ts
export class NotificationService {
notifyTaskAssignment(taskId: string, userId: string): void {
// Notification handling
}
}
// services/TaskService.ts
import { NotificationService } from './NotificationService';
export class TaskService {
constructor(private notificationService: NotificationService) {}
}
// services/UserService.ts
import { NotificationService } from './NotificationService';
export class UserService {
constructor(private notificationService: NotificationService) {}
}
```
## Scaling Strategy
### Recommended Structure
**Standard pattern**:
```
src/
├── commands/
│ └── TaskCommand.ts
├── services/
│ ├── TaskService.ts
│ └── UserService.ts
├── repositories/
│ ├── TaskRepository.ts
│ └── UserRepository.ts
├── types/
│ ├── Task.ts
│ └── User.ts
├── validators/
│ └── TaskValidator.ts
└── index.ts
```
**Rationale**:
- Responsibilities are clear per layer
- No later refactoring required
- Easy to standardize across a team
### Timing for Module Separation
**Signs that separation should be considered**:
1. A directory contains 10 or more files
2. Related functionality is grouped together
3. It can be tested independently
4. It has few dependencies on other features
**Separation procedure**:
```typescript
// Before: everything placed in services/
services/
├── TaskService.ts
├── TaskValidationService.ts
├── TaskNotificationService.ts
├── UserService.ts
└── UserAuthService.ts
// After: modularized by feature
modules/
├── task/
├── TaskService.ts
├── TaskValidationService.ts
└── TaskNotificationService.ts
└── user/
├── UserService.ts
└── UserAuthService.ts
```
## Handling Special Cases
### Placement of Shared Code
**shared/ or common/ directory**
```
src/
├── shared/
│ ├── utils/ # General-purpose utilities
│ ├── types/ # Shared type definitions
│ └── constants/ # Shared constants
├── commands/
├── services/
└── repositories/
```
**Rules**:
- Only things genuinely used across multiple layers
- Do not include anything used in only a single layer
### Managing Configuration Files (when applicable)
```
config/
├── default.ts # Default settings
└── constants.ts # Constant definitions
```
### Managing Scripts (when applicable)
```
scripts/
├── build.sh # Build script
└── dev-tools.ts # Development helper script
```
## Document Placement
### Document Types and Their Locations
**Project root**:
- `README.md`: Project overview
- `CONTRIBUTING.md`: Contribution guide
- `LICENSE`: License
**docs/ directory**:
- `product-requirements.md`: PRD
- `functional-design.md`: Functional design document
- `architecture.md`: Architecture design document
- `repository-structure.md`: This document
- `development-guidelines.md`: Development guidelines
- `glossary.md`: Glossary
**Within the source code**:
- TSDoc/JSDoc comments: Descriptions of functions and classes
## Checklist
- [ ] Each directory's role is clearly defined
- [ ] The layer structure is reflected in the directories
- [ ] Naming conventions are consistent
- [ ] The placement policy for test code is decided
- [ ] Dependency rules are clear
- [ ] There are no circular dependencies
- [ ] A scaling strategy has been considered
- [ ] Placement rules for shared code are defined
- [ ] A management method for configuration files is decided
- [ ] Document locations are clear

View File

@ -0,0 +1,306 @@
# Repository Structure Document
## Project Structure
```
project-root/
├── src/ # Source code
│ ├── [layer1]/ # [Description]
│ ├── [layer2]/ # [Description]
│ └── [layer3]/ # [Description]
├── tests/ # Test code
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # E2E tests
├── docs/ # Project documentation
├── config/ # Configuration files
└── scripts/ # Build/deploy scripts
```
## Directory Details
### src/ (Source Code Directory)
#### [Directory 1]
**Role**: [Description]
**Files placed here**:
- [File pattern 1]: [Description]
- [File pattern 2]: [Description]
**Naming conventions**:
- [Rule 1]
- [Rule 2]
**Dependencies**:
- May depend on: [Directory name]
- Must not depend on: [Directory name]
**Example**:
```
[Directory name]/
├── [example-file1].ts
└── [example-file2].ts
```
#### [Directory 2]
**Role**: [Description]
**Files placed here**:
- [File pattern 1]: [Description]
**Naming conventions**:
- [Rule 1]
**Dependencies**:
- May depend on: [Directory name]
- Must not depend on: [Directory name]
### tests/ (Test Directory)
#### unit/
**Role**: Placement of unit tests
**Structure**:
```
tests/unit/
└── src/ # Same structure as the src directory
└── [layer]/
└── [filename].test.ts
```
**Naming conventions**:
- Pattern: `[name of file under test].test.ts`
- Example: `TaskService.ts``TaskService.test.ts`
#### integration/
**Role**: Placement of integration tests
**Structure**:
```
tests/integration/
└── [feature]/ # Split into directories by feature
└── [scenario].test.ts
```
#### e2e/
**Role**: Placement of E2E tests
**Structure**:
```
tests/e2e/
└── [user-scenario]/ # By user scenario
└── [flow].test.ts
```
### docs/ (Documentation Directory)
**Documents placed here**:
- `product-requirements.md`: Product Requirements Document
- `functional-design.md`: Functional design document
- `architecture.md`: Architecture design document
- `repository-structure.md`: Repository structure document (this document)
- `development-guidelines.md`: Development guidelines
- `glossary.md`: Glossary
### config/ (Configuration File Directory - when applicable)
**Files placed here**:
- Configuration files
- Constant definition files
**Example**:
```
config/
├── default.ts
└── constants.ts
```
### scripts/ (Script Directory - when applicable)
**Files placed here**:
- Build scripts
- Development helper scripts
## File Placement Rules
### Source Files
| File type | Location | Naming convention | Example |
|------------|--------|---------|-----|
| [Type 1] | [Directory] | [Rule] | [Example] |
| [Type 2] | [Directory] | [Rule] | [Example] |
### Test Files
| Test type | Location | Naming convention | Example |
|-----------|--------|---------|-----|
| Unit test | tests/unit/ | [target].test.ts | TaskService.test.ts |
| Integration test | tests/integration/ | [feature].test.ts | task-crud.test.ts |
| E2E test | tests/e2e/ | [scenario].test.ts | user-workflow.test.ts |
### Configuration Files
| File type | Location | Naming convention |
|------------|--------|---------|
| Environment config | config/environments/ | [environment-name].ts |
| Tool config | Project root | [tool-name].config.js |
| Type definitions | src/types/ | [target].d.ts |
## Naming Conventions
### Directory Names
- **Layer directories**: plural, kebab-case
- Example: `services/`, `repositories/`, `controllers/`
- **Feature directories**: singular, kebab-case
- Example: `task-management/`, `user-authentication/`
### File Names
- **Class files**: PascalCase
- Example: `TaskService.ts`, `UserRepository.ts`
- **Function files**: camelCase
- Example: `formatDate.ts`, `validateEmail.ts`
- **Constant files**: UPPER_SNAKE_CASE
- Example: `API_ENDPOINTS.ts`, `ERROR_MESSAGES.ts`
### Test File Names
- Pattern: `[target].test.ts` or `[target].spec.ts`
- Example: `TaskService.test.ts`, `formatDate.spec.ts`
## Dependency Rules
### Dependencies Between Layers
```
UI layer
↓ (OK)
Service layer
↓ (OK)
Data layer
```
**Forbidden dependencies**:
- Data layer → Service layer (❌)
- Data layer → UI layer (❌)
- Service layer → UI layer (❌)
### Dependencies Between Modules
**No circular dependencies**:
```typescript
// ❌ Bad example: circular dependency
// fileA.ts
import { funcB } from './fileB';
// fileB.ts
import { funcA } from './fileA'; // Circular dependency
```
**Solution**:
```typescript
// ✅ Good example: extract a shared module
// shared.ts
export interface SharedType { /* ... */ }
// fileA.ts
import { SharedType } from './shared';
// fileB.ts
import { SharedType } from './shared';
```
## Scaling Strategy
### Adding Features
Placement policy when adding new features:
1. **Small features**: place in an existing directory
2. **Medium features**: create a subdirectory within a layer
3. **Large features**: separate into an independent module
**Example**:
```
src/
├── services/
│ ├── TaskService.ts # Existing feature
│ └── task-management/ # Separation of a medium feature
│ ├── TaskService.ts
│ ├── SubtaskService.ts
│ └── TaskCategoryService.ts
```
### Managing File Size
**Guidelines for splitting files**:
- A single file: 300 lines or fewer recommended
- 300-500 lines: consider refactoring
- 500 lines or more: splitting strongly recommended
**How to split**:
```typescript
// Bad example: all functionality in one file
// TaskService.ts (800 lines)
// Good example: split by responsibility
// TaskService.ts (200 lines) - CRUD operations
// TaskValidationService.ts (150 lines) - validation
// TaskNotificationService.ts (100 lines) - notification handling
```
## Special Directories
### .steering/ (Steering Files)
**Role**: Define "what to do this time" for a specific development task
**Structure**:
```
.steering/
└── [YYYYMMDD]-[task-name]/
├── requirements.md # Requirements for this task
├── design.md # Design of the changes
└── tasklist.md # Task list
```
**Naming convention**: `20250115-add-user-profile` format
### .opencode/ (opencode Settings)
**Role**: opencode settings and customization
**Structure**:
```
.opencode/
├── command/ # Slash commands
├── skills/ # Task-specific skills
└── agent/ # Subagent definitions
```
## Exclusion Settings
### .gitignore
Files that should be excluded in the project:
- `node_modules/`
- `dist/`
- `.env`
- `.steering/` (temporary files for task management)
- `*.log`
- `.DS_Store`
### .prettierignore, .eslintignore
Files that should be excluded by tooling:
- `dist/`
- `node_modules/`
- `.steering/`
- `coverage/`