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
2026-06-24 22:32:45 +02:00
commit ced279e2df
45 changed files with 7439 additions and 0 deletions
--- a/.opencode/skills/glossary-creation/SKILL.md
+++ b/.opencode/skills/glossary-creation/SKILL.md
@ -0,0 +1,55 @@
+---
+name: glossary-creation
+description: Detailed guide and template for creating a glossary. Use only when creating a glossary.
+---
+
+# Glossary Creation Skill
+
+This skill is a detailed guide for systematically defining project-specific terms and technical terms.
+
+## Prerequisites
+
+Before starting to create a glossary, confirm the following:
+
+### Recommended Documents
+
+1. **docs/product-requirements.md** (PRD)
+2. **docs/functional-design.md** (Functional Design Document)
+3. **docs/architecture.md** (Architecture Design Document)
+4. **docs/repository-structure.md** (Repository Structure)
+5. **docs/development-guidelines.md** (Development Guidelines)
+
+The glossary defines the terms used across all documents in a unified way.
+Extract terms from each document and organize them systematically.
+
+## Priority of Existing Documents
+
+**Important**: If an existing glossary is present at `docs/glossary.md`,
+follow the priority order below:
+
+1. **Existing glossary (`docs/glossary.md`)** - Highest priority
+   - Contains project-specific term definitions
+   - Takes precedence over this skill's guide
+
+2. **This skill's guide** - Reference material
+   - Generic templates and examples
+   - Use when no existing glossary exists, or as a supplement
+
+**When creating new**: Refer to this skill's template and guide
+**When updating**: Update while maintaining the structure and content of the existing glossary
+
+## Output Destination
+
+Save the created glossary to the following location:
+
+```
+docs/glossary.md
+```
+
+## Template Reference
+
+When creating a glossary, use the following template: ./template.md
+
+## Detailed Guide
+
+For a more detailed creation guide, refer to the following file: ./guide.md
--- a/.opencode/skills/glossary-creation/guide.md
+++ b/.opencode/skills/glossary-creation/guide.md
@ -0,0 +1,509 @@
+# Glossary Creation Guide
+
+## Basic principles
+
+### 1. Clear and consistent definitions
+
+Term definitions should eliminate ambiguity so that everyone who reads them arrives at the same understanding.
+
+**Bad example**:
+```markdown
+## Task
+What the user should do
+```
+
+**Good example**:
+```markdown
+## Task (Task)
+**Definition**: A unit of work that the user must complete. It has a title, description, due date,
+and status (not started / in progress / completed).
+
+**Related terms**: Subtask, Task group
+
+**Usage examples**:
+- "Add a task": Register a new task in the system
+- "Complete a task": Change the task's status to completed
+
+**Data model**: `src/types/Task.ts`
+```
+
+### 2. Include concrete examples
+
+Show concrete usage examples, not just abstract definitions.
+
+**Example**:
+```markdown
+## Priority (Priority)
+**Definition**: A three-level indicator showing a task's importance and urgency
+
+**Value definitions**:
+- `high`: Urgent and important. Requires immediate response
+- `medium`: Important but not urgent. Handle in a planned manner
+- `low`: Low in both importance and urgency. Handle if there is time
+
+**Decision criteria**:
+- high: Due within 24 hours, or blocking other tasks
+- medium: Due within one week
+- low: Due more than one week out, or no due date
+
+**Usage example**:
+```typescript
+const task: Task = {
+  title: 'Fix security vulnerability',
+  priority: 'high', // Requires urgent response
+};
+```
+```
+
+### 3. Link related terms
+
+Make the relationships between terms clear.
+
+**Example**:
+```markdown
+## Task (Task)
+**Definition**: [Definition]
+
+**Related terms**:
+- [Subtask](#subtask): A task broken down into smaller parts
+- [Task group](#task-group): Multiple tasks grouped together
+- [Status](#task-status): The progress state of a task
+
+**Parent-child relationship**:
+- Parent: Task group
+- Child: Subtask
+```
+
+## How to classify terms
+
+### Defining domain terms
+
+**Target**: Project-specific business concepts
+
+**Items to define**:
+```markdown
+## [Term]
+
+**Definition**: [A concise definition in 1-2 sentences]
+
+**Description**: [Detailed explanation, background, constraints]
+
+**Related terms**: [Other related terms]
+
+**Usage examples**: [Specific usage scenarios]
+
+**Data model**: [The relevant file path]
+
+**English notation**: [English term] (when there is global expansion)
+```
+
+**Example**:
+```markdown
+## Steering File (Steering File)
+
+**Definition**: A temporary document created for short-term task management
+
+**Description**:
+A steering file is placed in the `.steering/[YYYYMMDD]-[task-name]/` directory
+and is deleted 1-2 weeks after the task is completed. It contains the task specification,
+implementation notes, review records, and so on.
+
+**Related terms**:
+- [Persistent document](#persistent-document): A document stored for the long term
+- [Task mode](#task-mode): The development mode that uses steering files
+
+**Usage examples**:
+- "Create a steering file for adding a feature"
+- "After the task is completed, delete or archive the steering file"
+
+**Directory structure**:
+```
+.steering/
+└── 20250101-add-priority-feature/
+    ├── requirements.md      # The requirements for this task
+    ├── design.md            # The design of the changes
+    └── tasklist.md          # The task list
+```
+
+**English notation**: Steering File
+```
+
+### Defining technical terms
+
+**Target**: The technologies, frameworks, and tools in use
+
+**Items to define**:
+```markdown
+## [Technology name]
+
+**Definition**: [A concise description of the technology]
+
+**Official site**: [URL]
+
+**Use in this project**: [How it is used]
+
+**Version**: [Version in use]
+
+**Reason for selection**: [Why this technology was chosen]
+
+**Alternative technologies**: [Other options that were considered]
+
+**Related documents**: [Links to internal documents]
+
+**Configuration file**: [Path to the configuration file]
+```
+
+**Example**:
+```markdown
+## TypeScript
+
+**Definition**: A programming language that adds static typing to JavaScript
+
+**Official site**: https://www.typescriptlang.org/
+
+**Use in this project**:
+All source code is written in TypeScript to ensure type safety.
+
+**Version**: 5.3.x
+
+**Reason for selection**:
+- Improved maintainability in large-scale development
+- Improved development efficiency through editor completion
+- Error detection at compile time
+
+**Alternative technologies**:
+- JavaScript ESM: Cannot benefit from type checking
+- Flow: Inferior to TypeScript in ecosystem maturity
+
+**Related documents**:
+- [Architecture Design Document](./architecture.md#technology-stack)
+- [Development Guidelines](./development-guidelines.md#typescript-conventions)
+
+**Configuration file**: `tsconfig.json`
+```
+
+### Defining abbreviations and acronyms
+
+**Principles**:
+- State the full name clearly
+- On first appearance, write both the abbreviation and the full name
+- Avoid project-specific abbreviations (use only common abbreviations)
+
+**Example**:
+```markdown
+## CLI
+
+**Full name**: Command Line Interface
+
+**Meaning**: An interface operated from the command line
+
+**Use in this project**:
+Used as the main interface of the Devtask tool. Users operate tasks with commands like
+`devtask add "task"`.
+
+**Implementation**: `src/cli/` directory
+
+**Alternative interface**: A GUI version is under consideration as a future extension
+
+## TDD
+
+**Full name**: Test-Driven Development
+
+**Meaning**: A development method in which tests are written first and then the implementation follows
+
+**Application in this project**:
+TDD is adopted for all new feature development.
+
+**Procedure**:
+1. Write a test
+2. Run the test → confirm it fails
+3. Write the implementation
+4. Run the test → confirm it succeeds
+5. Refactor
+
+**Reference**: [Development Guidelines](./development-guidelines.md#tdd)
+```
+
+### Defining architecture terms
+
+**Target**: Concepts related to system design and patterns
+
+**Items to define**:
+```markdown
+## [Concept]
+
+**Definition**: [Explanation of the architecture concept]
+
+**Application in this project**: [The specific implementation method]
+
+**Advantages**: [Reasons for adoption]
+
+**Disadvantages**: [Constraints and trade-offs]
+
+**Related components**: [Related components]
+
+**Diagram**: [Structure diagram]
+
+**References**: [References or URLs]
+```
+
+**Example**:
+```markdown
+## Layered Architecture (Layered Architecture)
+
+**Definition**: A design pattern that divides a system into multiple layers by role,
+with a one-directional dependency from upper layers to lower layers
+
+**Application in this project**:
+A three-layer architecture is adopted:
+
+```
+UI layer (cli/)
+    ↓
+Service layer (services/)
+    ↓
+Data layer (repositories/)
+```
+
+**Responsibilities of each layer**:
+- UI layer: Accepting and displaying user input
+- Service layer: Implementing business logic
+- Data layer: Persisting and retrieving data
+
+**Advantages**:
+- Improved maintainability through separation of concerns
+- Easy to test (each layer can be tested independently)
+- A limited scope of impact from changes
+
+**Disadvantages**:
+- May be over-engineering for small-scale projects
+- Overhead in data conversion between layers
+
+**Dependency rules**:
+- ✅ UI layer → Service layer
+- ✅ Service layer → Data layer
+- ❌ Data layer → Service layer
+- ❌ Data layer → UI layer
+
+**Implementation location**: Reflected in the structure of the `src/` directory
+
+**References**:
+- [Architecture Design Document](./architecture.md)
+- [Repository Structure Definition Document](./repository-structure.md)
+```
+
+## Defining state transitions
+
+**Target**: The statuses or states of an entity
+
+**Definition method**:
+
+1. **Enumerate in table form**
+2. **State the transition conditions clearly**
+3. **Visualize with a Mermaid diagram**
+
+**Example**:
+```markdown
+## Task Status (Task Status)
+
+**Definition**: An enumerated type that indicates the progress state of a task
+
+**Possible values**:
+
+| Status | Meaning | Transition condition | Next state |
+|----------|------|---------|---------|
+| `todo` | Not started | Initial state when the task is created | `in_progress` |
+| `in_progress` | In progress | The user starts the task | `completed`, `todo` |
+| `completed` | Completed | The user completes the task | `todo` (can be reopened) |
+
+**State transition diagram**:
+```mermaid
+stateDiagram-v2
+    [*] --> todo: Task created
+    todo --> in_progress: Work started
+    in_progress --> completed: Completed
+    in_progress --> todo: Interrupted
+    completed --> todo: Reopened
+    completed --> [*]: Archived
+```
+
+**Implementation**:
+```typescript
+// src/types/Task.ts
+export type TaskStatus = 'todo' | 'in_progress' | 'completed';
+
+// Validation of state transitions
+function canTransition(
+  from: TaskStatus,
+  to: TaskStatus
+): boolean {
+  const validTransitions: Record<TaskStatus, TaskStatus[]> = {
+    todo: ['in_progress'],
+    in_progress: ['completed', 'todo'],
+    completed: ['todo'],
+  };
+  return validTransitions[from].includes(to);
+}
+```
+
+**Business rules**:
+- Direct transition from `todo` → `completed` is prohibited
+- A completed task can be reopened
+- An archived task cannot be changed
+```
+
+## Defining errors and exceptions
+
+**Target**: The error classes defined in the system
+
+**Items to define**:
+```markdown
+## [Error name]
+
+**Class name**: `[ErrorClassName]`
+
+**Inherits from**: `Error` or `[ParentError]`
+
+**Conditions for occurrence**: [When it occurs]
+
+**Error message format**: [The format of the message]
+
+**How to handle**:
+- User: [What the user should do]
+- Developer: [What the developer should do]
+
+**Error code**: [If applicable]
+
+**Log level**: [ERROR, WARN, INFO]
+
+**Implementation location**: [File path]
+
+**Usage example**: [Code example]
+```
+
+**Example**:
+```markdown
+## Validation Error (Validation Error)
+
+**Class name**: `ValidationError`
+
+**Inherits from**: `Error`
+
+**Conditions for occurrence**:
+Occurs when user input violates a business rule.
+
+**Error message format**:
+```
+[Field name]: [Error description]
+```
+
+**How to handle**:
+- User: Correct the input according to the error message
+- Developer: Confirm whether the validation logic is correct
+
+**Error code**: `VAL-XXX` (XXX is a 3-digit number)
+
+**Log level**: WARN (because it is a user-caused error)
+
+**Implementation location**: `src/errors/ValidationError.ts`
+
+**Usage example**:
+```typescript
+// Throwing the error
+if (title.length === 0) {
+  throw new ValidationError(
+    'Title is required',
+    'title',
+    title
+  );
+}
+
+// Handling the error
+try {
+  await taskService.create(data);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(`Input error: ${error.message}`);
+    console.error(`Field: ${error.field}`);
+  }
+}
+```
+
+**Related validations**:
+- Title: 1-200 characters
+- Due date: Now or later
+- Priority: One of high, medium, low
+```
+
+## Maintaining and updating terms
+
+### When to add a term
+
+**When you should add**:
+- A new concept has been introduced
+- A term that team members have asked about
+- A term that appears three or more times in the documentation
+- When an external service or API has been integrated
+
+**When you do not need to add**:
+- General programming terms (variables, functions, etc.)
+- Temporary terms used only once
+
+### Update workflow
+
+1. **Add or change a term**
+   - Add it to the appropriate category
+   - Fill in all definition items
+   - Link related terms
+
+2. **Review**
+   - Share with team members
+   - Confirm the validity of the definition
+
+3. **Record the change history**
+   - Update the change history table of the glossary
+   - Note it in the commit message
+
+4. **Confirm the scope of impact**
+   - Search for places where the term is used
+   - Update documents as needed
+
+### Managing the index
+
+**Organize in Japanese syllabary order / alphabetical order**:
+
+```markdown
+## Index
+
+### A-row
+- [Archive](#archive) - Process term
+- [Error handling](#error-handling) - Technical term
+
+### KA-row
+- [Coverage](#coverage) - Technical term
+
+### SA-row
+- [Steering file](#steering-file) - Domain term
+- [Status](#task-status) - Data model term
+
+### TA-row
+- [Task](#task) - Domain term
+- [TDD](#tdd) - Abbreviation
+
+### A-Z
+- [CLI](#cli) - Abbreviation
+- [TypeScript](#typescript) - Technical term
+```
+
+## Checklist
+
+- [ ] Every term is clearly defined
+- [ ] Concrete examples are included
+- [ ] Related terms are linked
+- [ ] Categories are appropriately classified
+- [ ] Technical terms include version information
+- [ ] Abbreviations include their full names
+- [ ] State transitions are illustrated with diagrams
+- [ ] Errors include how to handle them
+- [ ] The index is organized
+- [ ] The change history is recorded
--- a/.opencode/skills/glossary-creation/template.md
+++ b/.opencode/skills/glossary-creation/template.md
@ -0,0 +1,179 @@
+# Project Glossary
+
+## Overview
+
+This document manages the definitions of terms used within the project.
+
+**Updated**: [YYYY-MM-DD]
+
+## Domain Terms
+
+Terms related to project-specific business concepts and features.
+
+### [Term 1]
+
+**Definition**: [Clear definition]
+
+**Description**: [Detailed description]
+
+**Related Terms**: [Other related terms]
+
+**Usage Examples**:
+- [Example 1]
+- [Example 2]
+
+**English Notation**: [English Term]
+
+### [Term 2]
+
+**Definition**: [Clear definition]
+
+**Description**: [Detailed description]
+
+**Related Terms**: [Other related terms]
+
+**Usage Examples**:
+- [Example 1]
+- [Example 2]
+
+## Technical Terms
+
+Terms related to the technologies, frameworks, and tools used in the project.
+
+### [Technology 1]
+
+**Definition**: [Description of the technology]
+
+**Official Site**: [URL]
+
+**Usage in This Project**: [How it is used]
+
+**Version**: [Version used]
+
+**Related Documents**: [Links to internal documents]
+
+### [Technology 2]
+
+**Definition**: [Description of the technology]
+
+**Official Site**: [URL]
+
+**Usage in This Project**: [How it is used]
+
+**Version**: [Version used]
+
+## Abbreviations and Acronyms
+
+### [Abbreviation 1]
+
+**Full Name**: [Full Name]
+
+**Meaning**: [Description]
+
+**Usage in This Project**: [Where it is used]
+
+### [Abbreviation 2]
+
+**Full Name**: [Full Name]
+
+**Meaning**: [Description]
+
+**Usage in This Project**: [Where it is used]
+
+## Architecture Terms
+
+Terms related to system design and architecture.
+
+### [Concept 1]
+
+**Definition**: [Description of the architecture concept]
+
+**Application in This Project**: [How it is implemented]
+
+**Related Components**: [Related component names]
+
+**Diagram**:
+```
+[ASCII diagram or Mermaid diagram]
+```
+
+### [Concept 2]
+
+**Definition**: [Description of the architecture concept]
+
+**Application in This Project**: [How it is implemented]
+
+## Statuses and States
+
+Definitions of various statuses used within the system.
+
+### [Status Category 1]
+
+| Status | Meaning | Transition Condition | Next State |
+|----------|------|---------|---------|
+| [State 1] | [Description] | [Condition] | [Next State] |
+| [State 2] | [Description] | [Condition] | [Next State] |
+
+**State Transition Diagram**:
+```mermaid
+stateDiagram-v2
+    [*] --> State1
+    State1 --> State2: Condition A
+    State2 --> [*]
+```
+
+## Data Model Terms
+
+Terms related to databases and data structures.
+
+### [Entity 1]
+
+**Definition**: [Description of the entity]
+
+**Key Fields**:
+- `field1`: [Description]
+- `field2`: [Description]
+
+**Related Entities**: [Related entities]
+
+**Constraints**: [Unique constraints, foreign key constraints, etc.]
+
+## Errors and Exceptions
+
+Errors and exceptions defined in the system.
+
+### [Error Category 1]
+
+**Class Name**: `[ErrorClassName]`
+
+**Trigger Condition**: [When it occurs]
+
+**Resolution**: [How users/developers should handle it]
+
+**Error Code**: [If applicable]
+
+**Example**:
+```typescript
+throw new [ErrorClassName]('[message]');
+```
+
+## Calculations and Algorithms (if applicable)
+
+Terms related to specific calculation methods or algorithms.
+
+### [Calculation Method 1]
+
+**Definition**: [Description of the calculation method]
+
+**Formula**:
+```
+[Formula]
+```
+
+**Implementation Location**: `src/[path]/[file].ts`
+
+**Example**:
+```
+Input: [Example]
+Output: [Result]
+```