@manhnv319/codexkit 0.1.0

package/.codex/rules/team-coordination-rules.md

@@ -0,0 +1,90 @@
+# Team Coordination Rules
+
+> These rules only apply when operating as a teammate within an Agent Team.
+> They have no effect on standard sessions or subagent workflows.
+
+Rules for agents operating as teammates within an Agent Team.
+
+## File Ownership (CRITICAL)
+
+- Each teammate MUST own distinct files — no overlapping edits
+- Define ownership via glob patterns in task descriptions: `File ownership: src/api/*, src/models/*`
+- Lead resolves ownership conflicts by restructuring tasks or handling shared files directly
+- Tester owns test files only; reads implementation files but never edits them
+- If ownership violation detected: STOP and report to lead immediately
+
+## Git Safety
+
+- Prefer git worktrees for implementation teams — each dev in own worktree eliminates conflicts
+- Never force-push from a teammate session
+- Commit frequently with descriptive messages
+- Pull before push to catch merge conflicts early
+- If working in a git worktree, commit/push to the worktree branch — not main or dev
+
+## Communication Protocol
+
+- Use `SendMessage(type: "message")` for peer DMs — always specify recipient by name
+- Use `SendMessage(type: "broadcast")` ONLY for critical blocking issues affecting entire team
+- Mark tasks completed via `TaskUpdate` BEFORE sending completion message to lead
+- Include actionable findings in messages, not just "I'm done"
+- Never send structured JSON status messages — use plain text
+
+## CK Stack Conventions
+
+### Report Output
+- Save reports to `{CK_REPORTS_PATH}` (injected via hook, fallback: `plans/reports/`)
+- Naming: `{type}-{date}-{slug}.md` where type = your role (researcher, reviewer, debugger)
+- Sacrifice grammar for concision. List unresolved questions at end.
+
+### Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- No AI references in commit messages
+- Keep commits focused on actual code changes
+
+### Docs Sync (Implementation Teams Only)
+- After completing implementation tasks, lead MUST evaluate docs impact
+- State explicitly: `Docs impact: [none|minor|major]`
+- If impact: update `docs/` directory or note in completion message
+
+## Task Claiming
+
+- Claim lowest-ID unblocked task first (earlier tasks set up context for later ones)
+- Check `TaskList` after completing each task for newly unblocked work
+- Set task to `in_progress` before starting work
+- If all tasks blocked, notify lead and offer to help unblock
+
+## Plan Approval Flow
+
+When `plan_mode_required` is set:
+1. Research and plan your approach (read-only — no file edits)
+2. Send plan via `ExitPlanMode` — this triggers approval request to lead
+3. Wait for lead's `plan_approval_response`
+4. If rejected: revise based on feedback, resubmit
+5. If approved: proceed with implementation
+
+## Conflict Resolution
+
+- If two teammates need the same file: escalate to lead immediately
+- If a teammate's plan is rejected twice: lead takes over that task
+- If findings conflict between reviewers: lead synthesizes and documents disagreement
+- If blocked by another teammate's incomplete work: message them directly first, escalate to lead if unresponsive
+
+## Shutdown Protocol
+
+- Approve shutdown requests unless mid-critical-operation
+- Always mark current task as completed before approving shutdown
+- If rejecting shutdown, explain why concisely
+- Extract `requestId` from shutdown request JSON and pass to `shutdown_response`
+
+## Idle State (Normal Behavior)
+
+- Going idle after sending a message is NORMAL — not an error
+- Idle means waiting for input, not disconnected
+- Sending a message to an idle teammate wakes them up
+- Do not treat idle notifications as completion signals — check task status instead
+
+## Discovery
+
+- Read team config at `~/.codex/teams/{team-name}/config.json` to discover teammates
+- Always refer to teammates by NAME (not agent ID)
+- Names are used for: `recipient` in SendMessage, task `owner` in TaskUpdate

package/.codex/scripts/README.md

@@ -0,0 +1,150 @@
+# Claude Code Scripts
+
+Centralized utility scripts for Claude Code skills.
+
+## Installation
+
+Install required dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+## resolve_env.py
+
+Centralized environment variable resolver that follows Claude Code's hierarchy.
+
+### Priority Order (Highest to Lowest)
+
+1. **process.env** - Runtime environment variables (HIGHEST)
+2. **PROJECT/.agents/skills/\<skill\>/.env** - Project skill-specific
+3. **PROJECT/.agents/skills/.env** - Project shared across skills
+4. **PROJECT/.codex/.env** - Project global defaults
+5. **~/.codex/skills/\<skill\>/.env** - User skill-specific
+6. **~/.codex/skills/.env** - User shared across skills
+7. **~/.codex/.env** - User global defaults (LOWEST)
+
+### CLI Usage
+
+```bash
+# Resolve a variable for a specific skill
+python ~/.codex/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal
+
+# With verbose output
+python ~/.codex/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal --verbose
+
+# Find all locations where variable is defined
+python ~/.codex/scripts/resolve_env.py GEMINI_API_KEY --find-all
+
+# Show hierarchy for a skill
+python ~/.codex/scripts/resolve_env.py --show-hierarchy --skill ai-multimodal
+
+# Export format for shell sourcing
+eval $(python ~/.codex/scripts/resolve_env.py GEMINI_API_KEY --export)
+```
+
+### Python API Usage
+
+```python
+# Add to sys.path if needed
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path.home() / '.codex' / 'scripts'))
+
+from resolve_env import resolve_env, find_all, show_hierarchy
+
+# Simple resolution
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
+
+# With default value
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal', default='fallback-key')
+
+# With verbose output
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal', verbose=True)
+
+# Find all locations
+locations = find_all('GEMINI_API_KEY', skill='ai-multimodal')
+for description, value, path in locations:
+    print(f"{description}: {value}")
+
+# Show hierarchy
+show_hierarchy(skill='ai-multimodal')
+```
+
+### Integration Pattern
+
+Skills should use this script instead of implementing their own resolution logic:
+
+```python
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+
+# Import centralized resolver
+sys.path.insert(0, str(Path.home() / '.codex' / 'scripts'))
+from resolve_env import resolve_env
+
+# Resolve API key
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
+
+if not api_key:
+    print("Error: GEMINI_API_KEY not found")
+    print("Run: python ~/.codex/scripts/resolve_env.py --show-hierarchy --skill ai-multimodal")
+    sys.exit(1)
+
+# Use api_key...
+```
+
+### Benefits
+
+- **Consistent**: All skills use the same resolution logic
+- **Maintainable**: Single source of truth for hierarchy
+- **Debuggable**: Built-in verbose mode and find-all functionality
+- **Flexible**: Supports both project-local and user-global configs
+- **Clear**: Shows exactly where each value comes from
+
+### Testing
+
+```bash
+# Test without any config files
+python ~/.codex/scripts/resolve_env.py TEST_VAR --verbose
+
+# Test with environment variable
+export TEST_VAR=from-runtime
+python ~/.codex/scripts/resolve_env.py TEST_VAR --verbose
+
+# Test with skill context
+python ~/.codex/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal --find-all
+```
+
+## generate_catalogs.py
+
+Generate YAML catalogs from command and skill data files. Outputs to stdout by default for easy consumption by Claude.
+
+### Usage
+
+```bash
+# Generate skills catalog (outputs to stdout)
+python .codex/scripts/generate_catalogs.py --skills
+
+# Generate skills catalog to file
+python .codex/scripts/generate_catalogs.py --skills --output guide/SKILLS.yaml
+
+# Write to file instead of stdout
+python .codex/scripts/generate_catalogs.py --skills --output guide/SKILLS.yaml
+
+# View help
+python .codex/scripts/generate_catalogs.py --help
+```
+
+### Input Files
+
+Located in the same directory as the script:
+- `commands_data.yaml` - Source data for commands
+- `skills_data.yaml` - Source data for skills
+
+### Output
+
+By default, outputs YAML to stdout. Use `--output PATH` to write to a file instead.
+
+**Note:** The script can be run from any directory - it resolves input files relative to the script location.

package/.codex/scripts/ck-help.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""
+Backward-compatible wrapper for ck-help.
+
+Canonical implementation lives at:
+  .agents/skills/ck-help/scripts/ck-help.py
+"""
+
+import runpy
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    target = (
+        Path(__file__).resolve().parent.parent
+        / "skills"
+        / "ck-help"
+        / "scripts"
+        / "ck-help.py"
+    )
+
+    if not target.exists():
+        print(f"Error: canonical ck-help script not found: {target}", file=sys.stderr)
+        return 1
+
+    # Preserve argv; run canonical script as __main__.
+    runpy.run_path(str(target), run_name="__main__")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.codex/scripts/commands_data.yaml

@@ -0,0 +1,3 @@
+# Commands have been migrated to skills.
+# See .agents/skills/ck-help/scripts/skills_data.yaml for the current catalog.
+[]

package/.codex/scripts/fix-shebang-permissions.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Fix executable permissions based on shebang presence in .codex folder
+# - No shebang + executable → remove exec
+# - Has shebang + not executable → add exec
+
+set -uo pipefail
+
+changed=0
+skipped=0
+target_dir="${1:-.codex}"
+
+# Validate target exists
+[[ -e "$target_dir" ]] || { echo "Error: '$target_dir' not found" >&2; exit 1; }
+
+while IFS= read -r -d '' file; do
+    [[ -L "$file" ]] && continue
+    [[ ! -s "$file" ]] && continue
+
+    # Skip binary files
+    file -b --mime-encoding "$file" 2>/dev/null | grep -q binary && continue
+
+    first_line=$(head -c 100 "$file" 2>/dev/null | head -n1) || continue
+
+    # Strip UTF-8 BOM if present
+    first_line="${first_line#$'\xef\xbb\xbf'}"
+
+    if [[ -x "$file" ]] && [[ "$first_line" != "#!"* ]]; then
+        if chmod -x "$file" 2>/dev/null; then
+            echo "- exec: $file"
+            git add --chmod=-x "$file" 2>/dev/null || true
+            ((changed++)) || true
+        else
+            echo "WARN: chmod failed: $file" >&2
+            ((skipped++)) || true
+        fi
+    elif [[ ! -x "$file" ]] && [[ "$first_line" == "#!"* ]]; then
+        if chmod +x "$file" 2>/dev/null; then
+            echo "+ exec: $file"
+            git add --chmod=+x "$file" 2>/dev/null || true
+            ((changed++)) || true
+        else
+            echo "WARN: chmod failed: $file" >&2
+            ((skipped++)) || true
+        fi
+    fi
+done < <(find "$target_dir" -type f -print0)
+
+echo "✓ Fixed $changed files"
+[[ $skipped -gt 0 ]] && echo "⚠ Skipped $skipped files (permission denied)"
+exit 0

package/.codex/scripts/generate_catalogs.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Generate updated command and skill catalogs.
+
+Outputs YAML to stdout by default for easy consumption by Claude.
+Use --output to write to a specific file instead.
+"""
+
+import argparse
+import sys
+try:
+    import yaml
+except ModuleNotFoundError:
+    raise SystemExit(
+        "PyYAML is required. Install with: python3 -m pip install -r .codex/scripts/requirements.txt"
+    )
+from pathlib import Path
+from datetime import datetime
+
+# Script directory for resolving relative paths
+SCRIPT_DIR = Path(__file__).parent
+
+# Windows UTF-8 compatibility (use shared utility)
+try:
+    from win_compat import ensure_utf8_stdout
+    ensure_utf8_stdout()
+except ImportError:
+    if sys.platform == 'win32':
+        import io
+        if hasattr(sys.stdout, 'buffer'):
+            sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+
+def load_yaml(filename):
+    """Load YAML file from script directory with helpful error handling."""
+    primary = SCRIPT_DIR / filename
+
+    # skills_data canonical source moved under ck-help skill.
+    # SCRIPT_DIR is .codex/scripts/, parent is .claude/
+    if filename == 'skills_data.yaml':
+        canonical = SCRIPT_DIR.parent / 'skills' / 'ck-help' / 'scripts' / 'skills_data.yaml'
+        if canonical.exists():
+            loaded = yaml.safe_load(canonical.read_text(encoding='utf-8'))
+            return loaded if loaded is not None else []
+
+    if not primary.exists():
+        print(f"Error: {primary} not found", file=sys.stderr)
+        print(f"Hint: Run scan_skills.py or scan_commands.py first to generate data files", file=sys.stderr)
+        sys.exit(1)
+
+    loaded = yaml.safe_load(primary.read_text(encoding='utf-8'))
+    if loaded is None:
+        return []
+    return loaded
+
+
+def generate_commands_yaml():
+    """Generate COMMANDS.yaml catalog."""
+    commands = load_yaml('commands_data.yaml')
+
+    # Group by category
+    categories = {}
+    for cmd in commands:
+        cat = cmd['category']
+        if cat not in categories:
+            categories[cat] = []
+        categories[cat].append(cmd)
+
+    # Sort commands within each category
+    for cat in categories:
+        categories[cat] = sorted(categories[cat], key=lambda x: x['name'])
+
+    # Generate catalog structure
+    catalog = {
+        'metadata': {
+            'title': 'Commands Catalog',
+            'description': 'Auto-generated catalog of all available commands in ClaudeKit Engineer',
+            'last_updated': datetime.now().strftime('%Y-%m-%d'),
+            'total_commands': len(commands)
+        },
+        'categories': {
+            'core': 'Core Commands',
+            'bootstrap': 'Bootstrap Commands',
+            'content': 'Content Creation',
+            'cook': 'Cook Commands',
+            'design': 'Design Commands',
+            'docs': 'Documentation',
+            'fix': 'Fix & Debug',
+            'git': 'Git Commands',
+            'integrate': 'Integrations',
+            'plan': 'Planning',
+            'review': 'Code Review',
+            'scout': 'Scout Commands',
+            'skill': 'Skill Management'
+        },
+        'commands': categories
+    }
+
+    return yaml.dump(catalog, sort_keys=False, allow_unicode=True, default_flow_style=False)
+
+
+def generate_skills_yaml():
+    """Generate SKILLS.yaml catalog."""
+    skills = load_yaml('skills_data.yaml')
+
+    # Group by category
+    categories = {}
+    for skill in skills:
+        cat = skill['category']
+        if cat not in categories:
+            categories[cat] = []
+        categories[cat].append(skill)
+
+    # Sort skills within each category
+    for cat in categories:
+        categories[cat] = sorted(categories[cat], key=lambda x: x['name'])
+
+    # Generate catalog structure
+    catalog = {
+        'metadata': {
+            'title': 'Skills Catalog',
+            'description': 'Auto-generated catalog of all available skills in ClaudeKit Engineer',
+            'last_updated': datetime.now().strftime('%Y-%m-%d'),
+            'total_skills': len(skills)
+        },
+        'categories': {
+            'ai-ml': 'AI & Machine Learning',
+            'frontend': 'Frontend & Design',
+            'backend': 'Backend Development',
+            'infrastructure': 'Infrastructure & DevOps',
+            'database': 'Database & Storage',
+            'dev-tools': 'Development Tools',
+            'multimedia': 'Multimedia & Processing',
+            'frameworks': 'Frameworks & Platforms',
+            'utilities': 'Utilities & Helpers',
+            'core': 'Core Workflow',
+            'plan': 'Planning & Delivery',
+            'review': 'Code Review',
+            'test': 'Testing & QA',
+            'docs': 'Documentation',
+            'tools': 'Tooling',
+            'infra': 'Infrastructure',
+            'kanban': 'Kanban & Planning Board',
+            'worktree': 'Git Worktree',
+            'journal': 'Journaling',
+            'watzup': 'Session Wrap-up',
+            'other': 'Other'
+        },
+        'legend': {
+            'has_scripts': 'Has executable scripts',
+            'has_references': 'Has reference documentation'
+        },
+        'skills': categories
+    }
+
+    return yaml.dump(catalog, sort_keys=False, allow_unicode=True, default_flow_style=False)
+
+
+def write_output(content, output_path=None, label=None):
+    """Write content to stdout or file."""
+    if output_path:
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding='utf-8')
+        print(f"Generated {output_path}", file=sys.stderr)
+    else:
+        print(content)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description='Generate command and skill catalogs',
+        epilog='Outputs to stdout by default. Use --output to write to a file.'
+    )
+    parser.add_argument('--skills', action='store_true', help='Generate only skills catalog')
+    parser.add_argument('--commands', action='store_true', help='Generate only commands catalog')
+    parser.add_argument('--output', '-o', metavar='PATH', help='Write output to file instead of stdout')
+    args = parser.parse_args()
+
+    # Validate: --output requires exactly one of --skills or --commands
+    if args.output and not (args.skills ^ args.commands):
+        print("Error: --output requires exactly one of --skills or --commands", file=sys.stderr)
+        sys.exit(1)
+
+    # If no specific flag, generate both (to stdout only)
+    generate_both = not (args.skills or args.commands)
+
+    if args.commands or generate_both:
+        commands_yaml = generate_commands_yaml()
+        if generate_both:
+            print("# === COMMANDS CATALOG ===")
+        write_output(commands_yaml, args.output if args.commands else None)
+
+    if args.skills or generate_both:
+        skills_yaml = generate_skills_yaml()
+        if generate_both:
+            print("\n# === SKILLS CATALOG ===")
+        write_output(skills_yaml, args.output if args.skills else None)

package/.codex/scripts/requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0