aiwf 0.1.0 → 0.3.0

package/claude-code/aiwf/ko/.claude/CLAUDE_BE.md

@@ -0,0 +1,276 @@
+# CLAUDE.md
+
+IMPORTANT: These are my development preferences and guidelines. YOU MUST follow them when working on my projects.
+site: https://github.com/wcygan/dotfiles
+
+## Code Style & Workflow
+
+### Testing
+
+- **ALWAYS** write clear, descriptive test names for better readability
+- **ALWAYS** prefer running single tests over the whole test suite for performance
+- Use `deno test --filter="test name"` or framework-specific single test runners
+
+### Language & Framework Preferences
+
+#### Backend Programming
+
+IMPORTANT: I am primarily a backend developer and prefer these languages and frameworks:
+
+- **Go**: Use [ConnectRPC](https://github.com/connectrpc/connect-go) for RPC services
+- **Rust**: Use [axum](https://github.com/tokio-rs/axum) for web services
+- **Java**: Use [Spring Boot](https://spring.io/projects/spring-boot) with [Quarkus](https://quarkus.io/)
+
+#### Scripting & Automation
+
+**YOU MUST** use Deno for all scripting tasks instead of Bash or Python:
+
+- Create `deno.json` in project root with tasks for common operations
+- Use JSR imports: `import { walk } from "@std/fs";` NOT `https://deno.land/...`
+- Use [Dax](https://github.com/dsherret/dax) for cross-platform shell operations
+- Example deno.json imports: `"@std/fs": "jsr:@std/fs@^1.0.17"`
+
+#### Web Development
+
+Use [Deno Fresh](https://fresh.deno.dev/) with these practices:
+
+- Built-in test runner: `Deno.test()`
+- Organize tests: `/tests/unit/`, `/tests/component/`, `/tests/e2e/`
+- Mock external dependencies for fast, reliable tests
+- Use fresh-testing-library for component/handler testing
+
+## Infrastructure Choices
+
+IMPORTANT: I run a Talos Linux Kubernetes Cluster. Use these modern alternatives:
+
+- **Database**: Postgres (NOT MySQL)
+- **Cache**: DragonflyDB (NOT Redis)
+- **Streaming**: RedPanda (NOT Kafka)
+- **NoSQL**: ScyllaDB (NOT Cassandra)
+
+## Modern Development Tools
+
+### Preferred Command-Line Tools
+
+**ALWAYS** prefer these modern, fast alternatives:
+
+- **ripgrep (rg)**: Use instead of grep for searching code
+- **fd**: Use instead of find for finding files
+- **fzf**: Use for interactive fuzzy finding
+- **bat**: Use instead of cat for syntax-highlighted file viewing
+- **exa/eza**: Use instead of ls for better file listings
+- **delta**: Use for better git diffs
+- **zoxide**: Use instead of cd for smarter directory navigation
+- **duf**: Use instead of df for disk usage
+- **htop/btop**: Use instead of top for process monitoring
+- **jq**: Use for JSON processing and manipulation
+- **yq**: Use for YAML processing and manipulation
+- **hexyl**: Use for hex viewing of binary files
+
+### Output Format Preferences
+
+**ALWAYS** prefer JSON output for parsing when available:
+
+- Use `-o json` or `--json` flags when available (e.g., `kubectl get nodes -o json`)
+- Parse structured JSON output instead of text formats for reliability
+- Use `jq` for JSON processing in scripts
+- Examples:
+  - `kubectl get pods -o json | jq '.items[].metadata.name'`
+  - `docker inspect container-name | jq '.[0].State.Status'`
+  - `aws ec2 describe-instances --output json | jq '.Reservations[].Instances[]'`
+
+### Common Commands
+
+```bash
+# Modern tool usage
+rg "pattern" --type rust        # Search Rust files
+fd ".rs$" src/                   # Find all Rust files
+bat src/main.rs                  # View file with syntax highlighting
+eza -la --git                    # List files with git status
+delta                            # Better git diff viewer
+
+# Deno development
+deno task dev          # Start development server
+deno task test         # Run all tests
+deno test --filter="specific test"  # Run single test
+deno task build        # Build project
+deno check            # Type check
+deno fmt              # Format code
+deno lint             # Lint code
+
+# Project setup
+deno task init        # Initialize / configure the project for a new environment
+deno task deps        # Update dependencies
+
+# Git worktree (for multi-agent workflows)
+git worktree add ../project-feature feature-branch
+git worktree list
+git worktree remove ../project-feature
+```
+
+## Development Workflow
+
+1. **ALWAYS** run type checking/linting after code changes (e.g., `deno check`, `go vet`, `cargo check`)
+2. **ALWAYS** format code before committing using project's formatter
+3. **ALWAYS** run relevant tests before pushing changes
+4. **NEVER** commit without running pre-commit checks
+5. **ALWAYS** use semantic commit messages (feat:, fix:, docs:, refactor:, test:, chore:)
+
+### AI-Assisted Development Pattern
+
+1. **WRITE** failing tests first (test-driven development)
+2. **GENERATE** implementation with AI assistance
+3. **VERIFY** code meets requirements and security standards
+4. **REFACTOR** at appropriate checkpoints, not continuously
+5. **LOG** extensively for debugging AI-generated code
+
+### Context Management
+
+- **PROVIDE** clear, specific requirements to minimize context gaps
+- **INCLUDE** relevant project context in prompts
+- **DOCUMENT** assumptions and decisions in code comments
+
+## Security & Code Verification
+
+### AI-Generated Code Review
+
+- **ALWAYS** review and understand AI-generated code before accepting
+- **NEVER** commit code you don't fully understand
+- **RUN** security scanning on all generated code
+- **VERIFY** all third-party dependencies suggested by AI
+- **TEST** edge cases and error handling thoroughly
+
+### Sensitive Data Protection
+
+- **NEVER** share API keys, credentials, or proprietary code with AI
+- **USE** environment variables or secret management tools
+- **SANITIZE** logs and debug output before sharing
+
+## Project Planning & Coordination
+
+### PLAN.md Adherence
+
+When a `PLAN.md` file exists in the project root, **YOU MUST**:
+
+1. **READ** the PLAN.md file at the start of each session to understand current tasks and priorities
+2. **FOLLOW** the task breakdown and execution strategy defined in the plan
+3. **RESPECT** task dependencies and join points for multi-agent coordination
+4. **UPDATE** task status in the plan as work progresses
+5. **COORDINATE** with other agents at defined synchronization points
+6. **USE** the TodoWrite tool to track individual tasks from the plan
+
+### Multi-Agent Workflow
+
+When working as part of a multi-agent team:
+
+- **CHECK** `/tmp/{project-name}/project-status.md` or coordination files for shared state
+- **WORK** only on assigned tasks to avoid conflicts
+- **COMMUNICATE** progress through PR comments or status files
+- **WAIT** at join points until all parallel work is complete
+- **MERGE** work carefully following the plan's integration strategy
+- **USE** git worktrees to work on separate branches without conflicts
+- **CREATE** status files in `/tmp/{project-name}/claude-scratch/` for inter-agent communication
+- **COORDINATE** using shared JSON status files for structured updates in project-specific directories
+
+## Performance & Optimization
+
+### Token Efficiency
+
+- **OPTIMIZE** prompts for clarity and brevity
+- **BATCH** related operations in single requests
+- **USE** structured outputs (JSON) for parsing efficiency
+- **CACHE** common patterns and solutions locally
+
+### Parallel Development
+
+- **USE** Docker containers for isolated AI agent environments
+- **IMPLEMENT** clear synchronization points for multi-agent work
+- **MAINTAIN** shared state files in `/tmp/{project-name}/`
+
+## Task Management
+
+Use the task management system for tracking work items:
+
+- **Location**: Tasks are stored in `/tasks/` directory with `status.json` index
+- **Commands**: Use `/task-create`, `/task-update`, `/task-list`, `/task-show`, `/task-log`, `/task-search`, `/task-archive`
+- **Format**: Tasks are markdown files with structured metadata
+- **Integration**: Active tasks sync with TodoWrite for session tracking
+
+## File Organization
+
+- `/src/` - Source code
+- `/tests/` - Test files organized by type
+- `/scripts/` - Deno automation scripts
+- `/tasks/` - Task management files (markdown + status.json)
+- `deno.json` - Project configuration and tasks
+- `import_map.json` - Import mappings (if needed)
+
+## Documentation Style
+
+### README Files
+
+**KEEP README FILES CONCISE AND SCANNABLE:**
+
+- **Maximum 50 lines** for most projects
+- **No excessive emojis** or decorative elements
+- **Essential sections only**: Purpose, Quick Start, Key Commands
+- **No verbose explanations** - let code and comments speak
+- **Single quick start command** when possible
+- **Brief feature lists** without detailed descriptions
+- **Minimal project structure** - only if complex
+- **Essential links only** - avoid resource dumps
+
+**Example concise README:**
+
+````markdown
+# Project Name
+
+Brief one-line description of what it does.
+
+## Quick Start
+
+```bash
+deno task init && deno task dev
+```
+````
+
+## Key Commands
+
+- `deno task test` - Run tests
+- `deno task build` - Build project
+
+## Features
+
+- Core feature 1
+- Core feature 2
+- Core feature 3
+
+```
+**Avoid:**
+- Long feature descriptions
+- Extensive project structure diagrams
+- Multiple installation methods
+- Verbose technical explanations
+- Marketing-style language
+- Detailed configuration options in main README
+
+## Claude Code Features
+
+### Thinking Modes
+- `think` - Standard mode (4,000 tokens)
+- `think hard` - Enhanced analysis
+- `think harder` - Deep computation
+- `ultrathink` - Maximum analysis (31,999 tokens)
+
+### Effective Usage
+- **USE** thinking modes for complex architectural decisions
+- **AVOID** over-thinking simple tasks
+- **BALANCE** computation time with task complexity
+
+## IMPORTANT Notes
+
+- **YOU MUST** follow these guidelines exactly as written
+- **ALWAYS** ask for clarification if requirements conflict
+- **NEVER** use deprecated patterns or old import styles
+- **ALWAYS** prioritize performance and type safety
+```

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_changelog.md

@@ -0,0 +1,82 @@
+# Git 커밋 히스토리 기반 Changelog 자동 생성
+
+Git 커밋 히스토리를 분석하여 체계적인 changelog를 생성합니다.
+
+## 작업 단계
+
+### 1. Git 히스토리 분석
+- 최근 커밋들을 분석하여 변경사항 파악
+- 태그 정보 확인 (있는 경우)
+- 커밋 메시지에서 conventional commit 형식 파싱
+
+### 2. 변경사항 분류
+다음 카테고리로 커밋들을 분류:
+- ✨ Features (feat)
+- 🐛 Bug Fixes (fix)
+- 📝 Documentation (docs)
+- 🎨 Code Style (style)
+- ♻️ Refactoring (refactor)
+- ⚡ Performance (perf)
+- ✅ Tests (test)
+- 🔧 Build/Config (build, chore)
+
+### 3. Changelog 생성
+- CHANGELOG.md 파일 생성 또는 업데이트
+- 버전별로 섹션 구분 (태그 기반)
+- 각 카테고리별로 변경사항 정리
+- 커밋 SHA와 함께 표시
+
+### 4. 실행 방법
+```bash
+# 기본 실행 (전체 히스토리)
+/project:aiwf:changelog
+
+# 특정 커밋 범위 지정
+/project:aiwf:changelog v1.0.0..HEAD
+
+# 특정 개수의 최근 커밋
+/project:aiwf:changelog -n 50
+```
+
+### 5. 생성 예시
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### ✨ Features
+- feat(auth): 소셜 로그인 기능 추가 (abc1234)
+- feat(api): RESTful API v2 구현 (def5678)
+
+### 🐛 Bug Fixes
+- fix(ui): 모바일 반응형 레이아웃 수정 (ghi9012)
+
+### 📝 Documentation
+- docs(readme): 설치 가이드 업데이트 (jkl3456)
+```
+
+## 구현 내용
+
+1. Git 로그 파싱:
+```bash
+git log --pretty=format:"%h|%s|%an|%ad" --date=short
+```
+
+2. Conventional Commit 패턴 매칭:
+```regex
+^(feat|fix|docs|style|refactor|perf|test|build|chore)(\(.+\))?:\s+(.+)$
+```
+
+3. 태그 정보 활용:
+```bash
+git describe --tags --abbrev=0
+```
+
+4. Changelog 템플릿 적용 및 파일 생성
+
+5. 기존 CHANGELOG.md가 있는 경우 적절히 병합
+
+## 주의사항
+- Conventional Commit 형식을 따르지 않는 커밋은 "기타 변경사항"으로 분류
+- 병합 커밋은 기본적으로 제외
+- 생성된 changelog는 검토 후 수동 편집 가능

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_code_review.md

@@ -0,0 +1,88 @@
+# 코드 리뷰 - 탑 다운 실행
+
+Use the following instructions from top to bottom to execute a Code Review.
+
+## Create a TODO with EXACTLY these 6 Items
+
+1. Analyze the Scope given
+2. Find code changes within Scope
+3. Find relevant Specification and Documentation
+4. Compare code changes against Documentation and Requirements
+5. Analyze possible differences
+6. Provide PASS/FAIL verdict with details
+
+Follow step by step and adhere closely to the following instructions for each step.
+
+## DETAILS on every TODO item
+
+### 1. Analyze the Scope given
+
+check: <$ARGUMENTS>
+
+If empty, use default, otherwise interpret <$ARGUMENTS> to identify the scope of the Review. Only continue if you can find meaningful changes to review.
+
+**CONTEXT:** Before reviewing code changes:
+
+- Read `.aiwf/00_PROJECT_MANIFEST.md` to understand current sprint and milestone context
+- Use the manifest to identify which sprint is active and what work is in scope
+- Only evaluate against requirements appropriate for the current sprint's deliverables
+
+### 2. Find code changes within Scope
+
+With the identified Scope use `git diff` (on default: `git diff HEAD~1`) to find code changes.
+
+### 3. Find relevant Specifications and Documentation
+
+- FIND the Task, Sprint and Milestone involved in the work that was done and output your findings
+- Navigate to `.aiwf/03_SPRINTS/` to find the current sprint directory
+- READ the sprint meta file to understand sprint objectives and deliverables
+- If a specific task is in scope, find and READ the task file in the sprint directory
+- IDENTIFY related requirements in `.aiwf/02_REQUIREMENTS/` for the current milestone
+- READ involved Documents especially in `.aiwf/01_PROJECT_DOCS/` and `.aiwf/02_REQUIREMENTS/`
+- **IMPORTANT:** Focus on current sprint deliverables, not future milestone features
+
+### 4. Compare code changes against Documentation and Requirements
+
+- Use DEEP THINKING to compare changes against found Requirements and Specs.
+- Compare especially these things:
+  - **Data models / schemas** — fields, types, constraints, relationships.
+  - **APIs / interfaces** — endpoints, params, return shapes, status codes, errors.
+  - **Config / environment** — keys, defaults, required/optional.
+  - **Behaviour** — business rules, side-effects, error handling.
+  - **Quality** — naming, formatting, tests, linter status.
+
+**IMPORTANT**:
+
+- Deviations from the Specs is not allowed. Not even small ones. Be very picky here!
+- If in doubt call a **FAIL** and ask the User.
+- Zero tolerance on not following the Specs and Documentation.
+
+### 5. Analyze the differences
+
+- Analyze any difference found
+- Give every issue a Severity Score
+- Severity ranges from 1 (low) to 10 (high)
+- Remember List of issues and Scores for output
+
+### 6. Provide PASS/FAIL verdict with details
+
+- Call a **FAIL** on any differences found.
+  - Zero Tolerance - even on well meant additions.
+  - Leave it on the user to decide if small changes are allowed.
+- Only **PASS** if no discrepancy appeared.
+
+#### IMPORTANT: Output Format
+
+- Output the results of your review to the task's **## Output Log** section in the task file
+- Find the task file in `.aiwf/03_SPRINTS/` or `.aiwf/04_GENERAL_TASKS/` based on the scope
+- Append the review results to the existing Output Log with timestamp
+- Output Format:
+  ```
+  [YYYY-MM-DD HH:MM]: Code Review - PASS/FAIL
+  Result: **FAIL/PASS** Your final decision on if it's a PASS or a FAIL.
+  **Scope:** Inform the user about the review scope.
+  **Findings:** Detailed list with all Issues found and Severity Score.
+  **Summary:** Short summary on what is wrong or not.
+  **Recommendation:** Your personal recommendation on further steps.
+  ```
+- Also output a brief result summary to the console for immediate feedback

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_commit.md

@@ -0,0 +1,160 @@
+# 변경사항 분석 및 사용자 확인을 통한 논리적 git 커밋 생성
+
+Follow these instructions from top to bottom.
+
+## Create a TODO with EXACTLY these 6 items
+
+1. Parse arguments and analyze git status
+2. Review changes and group by logical commits
+3. Propose commit structure and messages
+4. Check if user approval is necessary
+5. Execute approved commits
+6. Report commit results
+
+---
+
+## 1 · Analyze git status and parse arguments
+
+- Run these commands in parallel for maximum efficiency: `git status`, `git diff --staged`, `git diff`
+- List all changed files with their folder structure to understand the scope
+
+### CRITICAL: Argument Interpretation Rules
+
+**Context Provided** (when <$ARGUMENTS> contains text):
+
+- If YOLO is part of the <$ARGUMENTS> it is meant to skip user Approval (see Step 4 on your Todo)
+- The other text in <$ARGUMENTS> represents a **task ID**, **sprint ID**, or other **contextual identifier** provided by the user
+- This is NOT a file path - it's a semantic context for filtering changes
+- **PRIMARY FOCUS**: Only commit files directly related to this context
+- **SECONDARY CONSIDERATION**: After handling the primary context, ask if user wants to commit other unrelated changes
+
+**Task ID Pattern** (e.g., T01_S02, TX03_S01, T003):
+
+- Sprint Tasks: `T<NN>_S<NN>` format (e.g., T01_S02, T03_S02)
+- Completed Sprint Tasks: `TX<NN>_S<NN>` format (e.g., TX01_S02, TX03_S01)
+- General Tasks: `T<NNN>` format (e.g., T001, T002)
+- Completed General Tasks: `TX<NNN>` format (e.g., TX001, TX002)
+- Search for this task ID in:
+  - `.aiwf/03_SPRINTS/` directory (for sprint tasks)
+  - `.aiwf/04_GENERAL_TASKS/` directory (for general tasks)
+  - Task metadata in files (look for `task_id: T01_S02` in frontmatter)
+  - Git diff content (to see if code comments or commits reference the task)
+- Identify ALL files that were modified as part of this task's implementation
+- This includes: source code, tests, configuration, and the task documentation file itself
+
+**Sprint ID Pattern** (e.g., S01, S02):
+
+- When only sprint ID is provided, commit all changes related to ANY task within that sprint
+- Search pattern: `T*_S<NN>` in the sprint directory
+- Example: "S02" would include changes for T01_S02, T02_S02, T03_S02, etc.
+
+**No Context Provided** (when <$ARGUMENTS> is empty):
+
+- Analyze all changes and group them logically
+- Propose separate commits for different logical units of work
+
+### Implementation Steps
+
+1. First, determine if <$ARGUMENTS> contains any text
+2. If yes, explicitly state: "Context provided: '$ARGUMENTS' - I will focus on changes related to this context"
+3. If it's a task ID pattern, find the task file and understand what was implemented
+4. Filter the changed files to only those related to the identified context
+5. If no files match the context, inform the user: "No changes found related to '$ARGUMENTS'"
+6. If unrelated changes exist, mention them but DO NOT include in initial commit proposal
+
+## 2 · Review changes and group by logical commits
+
+### PRIORITY: Context Filtering
+
+**If context provided in arguments**:
+
+1. **FILTER FIRST**: Separate changes into two groups:
+   - **Related to context**: Files that are part of the task/context implementation
+   - **Unrelated to context**: Everything else
+2. **FOCUS**: Only analyze the "related to context" group for the first commit
+3. **DEFER**: Keep the "unrelated" group for potential later commits (only if user requests)
+
+**Standard grouping logic** (for no-context or within-context grouping):
+
+- **Think about** which changes belong together logically:
+  - Task completion (group by task ID when applicable)
+  - Feature additions (group by feature scope)
+  - Configuration updates (group separately)
+  - Documentation updates (group by documentation type)
+  - Bug fixes (group by related functionality)
+- **Think carefully** to ensure each commit represents one logical change that can be understood and potentially reverted independently
+- Avoid mixing unrelated changes in the same commit
+- Consider dependencies between changes when ordering commits
+
+## 3 · Propose commit
+
+### Context-Aware Commit Proposal
+
+**When context was provided** (e.g., task ID):
+
+- **FIRST COMMIT**: Must contain ONLY files related to the provided context
+- State clearly: "This commit includes changes for $ARGUMENTS"
+- After this commit is done, then ask: "There are also unrelated changes in [list files]. Would you like me to create additional commits for these?"
+
+**When no context provided**:
+
+- Propose commits based on logical grouping of all changes
+
+For the next commit to create:
+
+- **Context**: If applicable, which task/context this commit addresses
+- **Files**: List the specific files to be included
+- **Commit message**: Use conventional commit format, be clear and concise
+  - **CRITICAL:** Must not contain any attribution to Claude, Anthropic, or AI assistance
+  - If task-related, include task ID in message (e.g., "feat(agents): implement T01_S02 coordinator agent" or "fix(api): resolve T003 authentication issue")
+  - **GitHub Issue Linking**: If task has a GitHub issue, include `fixes #123` or `relates to #456` in commit message
+- **Reasoning**: Brief explanation of why these changes belong together
+
+## 4 · Check if user approval is necessary
+
+If YOLO **IS** part of the <$ARGUMENTS> skip this and jump to next step.
+
+Otherwise ask the User for approval.
+
+- Show the complete commit plan including files and message
+- Wait for explicit user confirmation before proceeding
+- If user says no, ask what should be changed
+- If user wants to modify the commit message or scope, make adjustments
+
+## 5 · Execute approved commit and continue
+
+For the approved commit:
+
+- Stage the specified files with `git add`
+- **IMPORTANT:** We are using pre-commit hooks that will likely report shortcomings. You need to fix them. Don't skip validation unless there are open tasks adressing especially these problems.
+- **Create the commit** with the approved message
+- Verify commit was created successfully
+- **GitHub Issue Update (if applicable):**
+  - If task has a linked GitHub issue
+  - Add commit link comment to issue:
+    ```bash
+    gh issue comment {issue_number} --body "🔗 Commit: {commit_sha} - {commit_message}"
+    ```
+- **IMPORTANT:** If there are more commits remaining, return to step 3 for the next commit
+- Only proceed to step 6 when all commits are completed
+
+## 6 · Report commit results
+
+Provide summary:
+
+- **Commits Created**: List each commit with SHA and message
+- **Files Committed**: Total count of files committed
+- **Remaining Changes**: Any uncommitted changes still pending
+- **Repository Status**: Current git status after commits
+
+## 7 · Generate Changelog (Optional)
+
+After successful commits:
+
+- Ask user: "커밋이 완료되었습니다. Changelog를 업데이트하시겠습니까? (y/n)"
+- If yes, execute: `/project:aiwf:changelog`
+- This will:
+  - Analyze recent commit history
+  - Generate or update CHANGELOG.md
+  - Categorize changes by type (feat, fix, docs, etc.)
+  - Include the commits just created