aiwf 0.1.0 → 0.3.1

package/claude-code/aiwf/ko/.aiwf/02_REQUIREMENTS/M01_Backend_Setup/SPECS_API_V1.md

@@ -0,0 +1,232 @@
+# API Specifications V1
+
+This document provides detailed specifications for the API endpoints to be implemented in the backend.
+
+## Base URL
+
+All API endpoints are prefixed with: `/api/v1`
+
+## Authentication
+
+All authenticated endpoints require a valid JWT token in the Authorization header:
+
+```
+Authorization: Bearer <token>
+```
+
+## Error Handling
+
+All API endpoints follow a consistent error response format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "details": {} // Optional additional error details
+  }
+}
+```
+
+Common error codes:
+- `UNAUTHORIZED`: Authentication required or invalid
+- `FORBIDDEN`: Insufficient permissions
+- `NOT_FOUND`: Resource not found
+- `VALIDATION_ERROR`: Request validation failed
+- `INTERNAL_ERROR`: Server-side error
+
+## Endpoints
+
+### Authentication
+
+#### POST /api/v1/auth/register
+
+Register a new user.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "name": "John Doe"
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "user": {
+    "id": "user123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "created_at": "2023-07-10T12:00:00Z"
+  },
+  "token": "jwt.token.here"
+}
+```
+
+#### POST /api/v1/auth/login
+
+Authenticate a user.
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "user": {
+    "id": "user123",
+    "email": "user@example.com",
+    "name": "John Doe",
+    "created_at": "2023-07-10T12:00:00Z"
+  },
+  "token": "jwt.token.here"
+}
+```
+
+### Users
+
+#### GET /api/v1/users/me
+
+Get current authenticated user profile.
+
+**Response (200 OK):**
+```json
+{
+  "id": "user123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "created_at": "2023-07-10T12:00:00Z",
+  "role": "user",
+  "status": "active"
+}
+```
+
+#### PUT /api/v1/users/me
+
+Update current user profile.
+
+**Request:**
+```json
+{
+  "name": "John Smith",
+  "avatar_url": "https://example.com/avatar.jpg"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "id": "user123",
+  "email": "user@example.com",
+  "name": "John Smith",
+  "avatar_url": "https://example.com/avatar.jpg",
+  "created_at": "2023-07-10T12:00:00Z",
+  "role": "user",
+  "status": "active"
+}
+```
+
+### Projects
+
+#### GET /api/v1/projects
+
+List all projects accessible to the authenticated user.
+
+**Query Parameters:**
+- `status` (optional): Filter by status (active, archived)
+- `limit` (optional): Maximum number of results (default: 20)
+- `offset` (optional): Pagination offset (default: 0)
+
+**Response (200 OK):**
+```json
+{
+  "total": 42,
+  "data": [
+    {
+      "id": "proj123",
+      "title": "Project Alpha",
+      "description": "This is project alpha",
+      "created_at": "2023-07-10T12:00:00Z",
+      "owner": {
+        "id": "user123",
+        "name": "John Doe"
+      },
+      "status": "active"
+    },
+    ...
+  ]
+}
+```
+
+#### POST /api/v1/projects
+
+Create a new project.
+
+**Request:**
+```json
+{
+  "title": "New Project",
+  "description": "Description of the project"
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "id": "proj456",
+  "title": "New Project",
+  "description": "Description of the project",
+  "created_at": "2023-07-15T14:30:00Z",
+  "owner": {
+    "id": "user123",
+    "name": "John Doe"
+  },
+  "status": "active"
+}
+```
+
+### Tasks
+
+#### GET /api/v1/projects/:projectId/tasks
+
+List tasks for a specific project.
+
+**Query Parameters:**
+- `status` (optional): Filter by status (todo, in_progress, done)
+- `assigned_to` (optional): Filter by assigned user ID
+- `limit` (optional): Maximum number of results (default: 50)
+- `offset` (optional): Pagination offset (default: 0)
+
+**Response (200 OK):**
+```json
+{
+  "total": 24,
+  "data": [
+    {
+      "id": "task123",
+      "title": "Implement login page",
+      "description": "Create the login page with email and password fields",
+      "due_date": "2023-08-01T00:00:00Z",
+      "status": "in_progress",
+      "priority": "high",
+      "assigned_to": {
+        "id": "user123",
+        "name": "John Doe"
+      },
+      "project_id": "proj123"
+    },
+    ...
+  ]
+}
+```
+
+## Rate Limiting
+
+API requests are rate-limited to 100 requests per minute per user. When the limit is exceeded, the API will respond with status code 429 (Too Many Requests).

package/claude-code/aiwf/ko/.aiwf/03_SPRINTS/CLAUDE.md

@@ -0,0 +1,83 @@
+# Sprint Management Instructions
+
+## Important Section - Always read
+
+- When updating Tasks Logs (Output Log) always fetch current date and time first
+- Update Output Log after every Subtask
+- Always be truthful in Logs. If you cannot complete a task for technical reasons, just write it down. Don't lie!
+- Only mark lines as done if you could acctually progress them.
+- Update the task file after every completed subtask and check Acceptance criteria as well if successful.
+
+## Sprint Structure
+
+Sprints are organized by milestone and sequence:
+
+- Folders follow pattern: `S<NN>_M<NN>_<Focus_Area>/` where:
+  - `S<NN>` is the sprint sequence number
+  - `M<NN>` directly references the milestone ID this sprint belongs to
+  - `<Focus_Area>` describes the sprint's main focus
+- Each sprint has a meta file: `S<NN>_sprint_meta.md`
+- Tasks use pattern: `T<NN>_S<NN>_<Description>.md`
+
+## Sprint Meta Files
+
+Sprint meta files define sprint goals and track status:
+
+```yaml
+---
+sprint_id: S01
+milestone_id: M01
+status: in_progress # planning | in_progress | review | complete
+---
+```
+
+Update status as progress occurs:
+
+- planning → in_progress → review → complete
+
+Always use the template at `.AIWF/99_TEMPLATES/sprint_template.md` when creating new sprint meta files.
+
+## Sprint Tasks
+
+Tasks within a sprint follow a standard format:
+
+- Status progression: open → in_progress → pending_review → done
+- When completing a task:
+  - Ask for user confirmation
+  - Update status to "done"
+  - Rename file from T... to TX... (e.g., `TX01_S01_Task_Name.md`)
+  - Update Output Log with final entry
+  - If GitHub issue is linked, update issue status
+
+Always use the template at `.AIWF/99_TEMPLATES/task_template.md` when creating new sprint tasks.
+
+### GitHub Issue Integration
+
+When working with tasks that have GitHub issues:
+
+1. **Creating Issues**: Use `/project:aiwf:issue_create {task_id}` to create a GitHub issue from a task
+2. **Linking Issues**: Add `github_issue: #123` to task frontmatter
+3. **Status Updates**: Update issue status when task status changes
+4. **Commit Integration**: Include `fixes #123` or `relates to #456` in commit messages
+5. **Pull Requests**: Use `/project:aiwf:pr_create {task_id}` to create PR with issue linking
+
+## Working with Sprint Tasks
+
+When executing a sprint task:
+
+1. Analyze task's Acceptance Criteria and Subtasks
+2. Check if task has a linked GitHub issue (look for `github_issue` in frontmatter)
+3. Update status to "in_progress" and update GitHub issue if linked:
+   ```bash
+   gh issue comment {issue_number} --body "🚀 Task work has started."
+   gh issue edit {issue_number} --add-label "in-progress"
+   ```
+4. Log activities in the Output Log with timestamps after every Subtask(!)
+5. Mark subtasks as completed using [x] only when they are really completed. If you were not able to complete them, don't mark them and tell the user.
+6. Reference architectural guidelines when implementing technical solutions
+7. Ensure the task follows the structure from the task template
+8. When task is complete, update GitHub issue if linked:
+   ```bash
+   gh issue comment {issue_number} --body "✅ Task has been completed."
+   gh issue edit {issue_number} --remove-label "in-progress" --add-label "completed"
+   ```

package/claude-code/aiwf/ko/.aiwf/03_SPRINTS/S01_M01_Initial_API/S01_sprint_meta.md

@@ -0,0 +1,49 @@
+---
+sprint_folder_name: S01_M01_Initial_API
+sprint_sequence_id: S01
+milestone_id: M01
+title: Initial API Development
+status: active # pending | active | completed | aborted
+goal: Implement the foundational API structure including user authentication, basic project endpoints, and the initial database models.
+last_updated: 2023-07-15
+---
+
+# Sprint: Initial API Development (S01) (EXAMPLE)
+
+## Sprint Goal
+
+Implement the foundational API structure including user authentication, basic project endpoints, and the initial database models.
+
+## Scope & Key Deliverables
+
+1. Set up the project structure with Express.js and MongoDB
+2. Implement user registration and authentication endpoints
+3. Create basic project and task models
+4. Implement core API endpoints for projects and tasks
+5. Set up automated testing infrastructure
+
+## Sprint Backlog
+
+- [T01_S01_Setup_Project_Structure](./T01_S01_Setup_Project_Structure.md)
+- [T02_S01_Define_User_Model](./T02_S01_Define_User_Model.md)
+- [T03_S01_Implement_Auth_Endpoints](./T03_S01_Implement_Auth_Endpoints.md)
+- [T04_S01_Define_Project_Model](./T04_S01_Define_Project_Model.md)
+- [T05_S01_Implement_Project_Endpoints](./T05_S01_Implement_Project_Endpoints.md)
+
+## Definition of Done (for the Sprint)
+
+The sprint will be considered complete when:
+
+- All sprint tasks are completed and meet their acceptance criteria
+- All implemented endpoints pass their test cases
+- API documentation is updated to reflect implemented endpoints
+- Code has been reviewed and merged to the development branch
+
+## Notes / Context
+
+This is an example sprint document to demonstrate how sprints might be structured in a project using the AIWF framework. This simulates what a typical initial API development sprint might look like.
+
+## Related Documents
+
+- [Milestone M01: Backend Setup](../../02_REQUIREMENTS/M01_Backend_Setup/M01_milestone_meta.md)
+- [API Specifications V1](../../02_REQUIREMENTS/M01_Backend_Setup/SPECS_API_V1.md)

package/claude-code/aiwf/ko/.aiwf/03_SPRINTS/S01_M01_Initial_API/T01_S01_Setup_Project_Structure.md

@@ -0,0 +1,60 @@
+---
+task_id: T01_S01
+sprint_sequence_id: S01
+status: in_progress # open | in_progress | pending_review | done | failed | blocked
+complexity: Medium # Low | Medium | High
+last_updated: 2023-07-15
+---
+
+# Task: Setup Project Structure (EXAMPLE)
+
+## Description
+
+Set up the initial project structure for the backend API service, including directory organization, dependency installation, and basic configuration.
+
+**Note: This is an example task to demonstrate the structure of a task in the AIWF framework.**
+
+## Goal / Objectives
+
+- Create a well-organized, scalable project structure
+- Set up the Express.js application with middleware
+- Configure MongoDB connection
+- Implement basic error handling
+- Set up environment configuration
+- Initialize logging system
+
+## Acceptance Criteria
+
+- [ ] Project structure follows MVC pattern with clear separation of concerns
+- [ ] Express application is set up with necessary middleware (CORS, body-parser, etc.)
+- [ ] MongoDB connection is configured with error handling
+- [ ] Environment variables are properly managed (development vs production)
+- [ ] Logger is implemented for request/error tracking
+- [ ] Basic error handling middleware is implemented
+- [ ] Project runs without errors
+- [ ] Initial tests pass
+
+## Subtasks
+
+- [ ] Initialize Node.js project with package.json
+- [ ] Install core dependencies (express, mongoose, dotenv, etc.)
+- [ ] Create directory structure for routes, controllers, models, middleware
+- [ ] Set up Express application with basic middleware
+- [ ] Configure MongoDB connection
+- [ ] Implement environment-specific configurations
+- [ ] Set up logging system
+- [ ] Implement error handling middleware
+- [ ] Write basic tests to verify configuration
+
+## Output Log
+
+[2023-07-15 14:30:00] Started task
+[2023-07-15 14:45:22] Created files: package.json, .env.example
+[2023-07-15 15:10:05] Created directory structure and base files: app.js, server.js, config/db.js, config/env.js
+[2023-07-15 15:30:18] Created middleware: middleware/auth.js, middleware/error.js
+[2023-07-15 15:45:30] Created util files: utils/logger.js
+[2023-07-15 16:10:15] Created base routes: routes/index.js
+[2023-07-15 16:45:22] Implemented error handling in middleware/error.js
+[2023-07-15 17:20:10] Configured logging system in utils/logger.js
+[2023-07-15 18:20:45] Added Jest configuration and created sample tests
+[2023-07-15 18:35:30] Completed all subtasks, verified server starts successfully

package/claude-code/aiwf/ko/.aiwf/04_GENERAL_TASKS/CLAUDE.md

@@ -0,0 +1,96 @@
+# General Tasks Instructions
+
+## General Task Structure
+
+General tasks are standalone work items not tied to sprints:
+
+- Files follow pattern: `T<NNN>_<Description>.md`
+- Completed tasks: `TX<NNN>_<Description>.md`
+
+Always use the template at `.AIWF/99_TEMPLATES/task_template.md` when creating new general tasks.
+
+## Task Formatting
+
+General tasks use standardized YAML frontmatter and sections:
+
+```yaml
+---
+task_id: T001
+status: open # open | in_progress | pending_review | done | failed | blocked
+complexity: Medium # Low | Medium | High
+last_updated: YYYY-MM-DD HH:MM
+github_issue: #123 # Optional: Link to GitHub issue
+---
+```
+
+The full task structure with all sections is defined in the task template. Always maintain this structure.
+
+## Working with General Tasks
+
+When handling general tasks:
+
+1. Check if task has a linked GitHub issue (look for `github_issue` in frontmatter)
+2. Update the status field as you progress
+3. If GitHub issue is linked, update it when starting:
+   ```bash
+   gh issue comment {issue_number} --body "🚀 Task work has started."
+   gh issue edit {issue_number} --add-label "in-progress"
+   ```
+4. Record timestamps in this format (YYYY-MM-DD HH:MM)
+5. Log all significant actions in the Output Log section:
+
+   ```plaintext
+   [YYYY-MM-DD HH:MM] Started task
+   [YYYY-MM-DD HH:MM] Modified files: file1.js, file2.js
+   ```
+
+6. Mark subtasks as they're completed: `- [x] Completed subtask`
+7. Use the Acceptance Criteria as your primary completion checklist
+8. Ensure all sections from the task template are preserved
+
+## Task Completion Process
+
+When a task is complete:
+
+1. Update status to "done"
+2. Update all Acceptance Criteria with [x]
+3. Add final Output Log entry
+4. If GitHub issue is linked, update it:
+   ```bash
+   gh issue comment {issue_number} --body "✅ Task has been completed."
+   gh issue edit {issue_number} --remove-label "in-progress" --add-label "completed"
+   ```
+5. Rename file from T... to TX... (e.g., `TX001_Task_Name.md`)
+
+## GitHub Integration
+
+### Creating Issues from Tasks
+
+To create a GitHub issue from a general task:
+
+```bash
+/project:aiwf:issue_create {task_id}
+```
+
+### Linking Existing Issues
+
+Add to task frontmatter:
+
+```yaml
+github_issue: #123
+```
+
+### Commit Integration
+
+When committing changes for a task with a linked issue:
+
+- Use `fixes #123` to auto-close the issue
+- Use `relates to #123` to reference without closing
+
+### Pull Request Creation
+
+After task completion, create a PR:
+
+```bash
+/project:aiwf:pr_create {task_id}
+```

package/claude-code/aiwf/ko/.aiwf/04_GENERAL_TASKS/T002_API_Rate_Limiting.md

@@ -0,0 +1,54 @@
+---
+task_id: T002
+status: in_progress # open | in_progress | pending_review | done | failed | blocked
+complexity: Medium # Low | Medium | High
+last_updated: 2023-07-25T09:15:00Z
+---
+
+# Task: API Rate Limiting (EXAMPLE)
+
+## Description
+
+Implement rate limiting for the API to prevent abuse and ensure fair usage across all clients. This task involves adding middleware to track and limit requests based on client IP or API key.
+
+**Note: This is an example general task to demonstrate how non-sprint-specific tasks might be structured in the AIWF framework.**
+
+## Goal / Objectives
+
+- Protect API endpoints from abuse and excessive requests
+- Implement configurable rate limits based on client authentication
+- Track usage statistics for billing and monitoring
+- Provide clear feedback to clients when limits are exceeded
+- Ensure minimal performance impact on normal API operation
+
+## Acceptance Criteria
+
+- [ ] Rate limiting is applied to all public API endpoints
+- [ ] Different rate limits are configurable based on client tier/authentication
+- [ ] Response headers include rate limit information (limit, remaining, reset)
+- [ ] When limit is exceeded, a 429 status code is returned with appropriate error message
+- [ ] Rate limiting can be temporarily disabled for specific clients if needed
+- [ ] Implementation has minimal impact on response times (<10ms overhead)
+- [ ] Usage statistics are collected for monitoring and analysis
+
+## Subtasks
+
+- [x] Research rate limiting strategies and best practices
+- [x] Evaluate libraries (express-rate-limit, rate-limiter-flexible, etc.)
+- [x] Design rate limit tiers for different client types
+- [ ] Implement rate limiting middleware
+- [ ] Add custom response headers
+- [ ] Create storage adapter for distributed rate limiting
+- [ ] Implement override mechanism for special cases
+- [ ] Add monitoring and alerts for rate limit events
+- [ ] Document rate limiting behavior for API consumers
+
+## Output Log
+
+_(This section is populated as work progresses on the task)_
+
+[2023-07-23 10:30:00] Started task
+[2023-07-23 13:45:22] Completed research on rate limiting strategies
+[2023-07-24 09:15:30] Evaluated rate-limiter-flexible and express-rate-limit libraries
+[2023-07-24 15:50:15] Decided on rate-limiter-flexible for implementation
+[2023-07-25 09:15:00] Designed rate limit tiers for different client authentication levels

package/claude-code/aiwf/ko/.aiwf/04_GENERAL_TASKS/TX001_Refactor_Logging_Module.md

@@ -0,0 +1,58 @@
+---
+task_id: T001
+status: done # open | in_progress | pending_review | done | failed | blocked
+complexity: Medium # Low | Medium | High
+last_updated: 2023-07-22T16:45:00Z
+---
+
+# Task: Refactor Logging Module (EXAMPLE)
+
+## Description
+
+The current logging implementation is basic and needs to be enhanced to provide better visibility and monitoring capabilities. This task involves refactoring the logging module to add structured logging, log rotation, and improved error tracking.
+
+**Note: This is an example general task to demonstrate how non-sprint-specific tasks might be structured in the AIWF framework.**
+
+## Goal / Objectives
+
+- Implement structured JSON logging for better parsing by log analysis tools
+- Add log rotation to prevent log files from growing too large
+- Enable different log levels based on environment
+- Add request ID tracking for tracing requests through the system
+- Improve error logging with stack traces and contextual information
+
+## Acceptance Criteria
+
+- [x] Logs are output in structured JSON format
+- [x] Log files are rotated based on size and/or date
+- [x] Different log levels are used appropriately (debug, info, warn, error)
+- [x] Each request has a unique ID that is logged with every related log entry
+- [x] Error logs include stack traces and relevant request information
+- [x] Performance impact of logging is minimal
+- [x] Documentation is updated to reflect new logging capabilities
+
+## Subtasks
+
+- [x] Evaluate and select appropriate logging libraries and tools
+- [x] Design the structured log format with required fields
+- [x] Implement log rotation configuration
+- [x] Add request ID middleware for request tracking
+- [x] Enhance error logging with more contextual information
+- [x] Update logging throughout the application to use new formats
+- [x] Write tests for logging functionality
+- [x] Document the new logging system
+
+## Output Log
+
+_(This section is populated as work progresses on the task)_
+
+[2023-07-15 10:30:00] Started task
+[2023-07-15 11:15:22] Researched logging libraries: winston, pino, bunyan
+[2023-07-15 13:45:30] Created prototype with winston for structured JSON logging
+[2023-07-15 15:20:15] Implemented log rotation with winston-daily-rotate-file
+[2023-07-15 16:40:05] Added request ID middleware
+[2023-07-15 17:30:18] Enhanced error logging with stack traces and context
+[2023-07-16 09:15:40] Updated application code to use new logging format
+[2023-07-18 14:22:10] Wrote tests for logging functionality
+[2023-07-20 11:05:33] Updated documentation with logging guidelines
+[2023-07-22 16:45:00] Task completed