Taskfile Commands and Development Workflow
This repository uses Taskfile for task automation and development workflows. Understanding and using these tasks is essential for effective development and troubleshooting.
Updating This File
This file should be regenerated when new tasks are added. Run task docs:taskfile to update it with the latest task list.
Key Development Principles
- MUST Use tasks instead of raw commands - If you regularly execute a command, it should be in a Taskfile
- MUST Leverage existing workflows - Many common operations already have tasks defined
- MUST Follow the ArgoCD development workflow - Pause ArgoCD sync for local testing, then resume when ready
- MUST Refactor and reuse - Identify duplication and refactor, including into the dev-common shared tasks
Common Command Mappings
❌ NEVER run these raw commands - use tasks instead:
| Raw Command | ✅ Use Task Instead |
|---|---|
kubectl apply -k path/ | task infra:apply |
kubectl logs -f deployment/X | task infra:logs |
docker build -t image . | task infra:build |
pytest or python -m pytest | task test or task metrics:test |
python script.py | Check for task <component>:<action> |
Before running ANY command, check if a task exists for it.
Available Tasks
The following tasks are available in this repository. Use task --list to see the most current list:
| Name | Description |
|---|---|
| builder:add-repos | Add additional repository worktrees to existing builder workspace (usage - task builder:add-repos BUILDER_NAME=my-feature REPOS=ai-dev,domain-apis) |
| builder:attach | Attach to builder workspace tmux session (usage - task builder:attach BUILDER_NAME=my-feature) |
| builder:cleanup | Remove builder workspace (usage - task builder:cleanup BUILDER_NAME=my-feature) |
| builder:control | Open control center view of all builder workspaces |
| builder:init | Initialize builder workspace with multi-repo support (usage - task builder:init BUILDER_NAME=my-feature REPOS=ai-dev) |
| builder:list | List all builder workspaces |
| builder:open | Open builder workspace (usage - task builder:open BUILDER_NAME=my-feature [IDE=code |
| builder:send | Send command to builder workspace session (usage - task builder:send BUILDER_NAME=my-feature CMD=“git status”) |
| builders:status | Show git status for all builders and their repositories |
| docs:taskfile | Generate/update the taskfile steering documentation |
| projects:create | Create a new project (usage - task projects:create NAME=my-project FORMAT=kiro CATEGORY=infrastructure) |
| projects:index | Generate project index at .ai/projects/INDEX.md |
| projects:list | List all projects with their status and category |
| projects:sync | Sync project metadata with artifacts (usage - task projects:sync [PROJECT=name]) |
| shared:dev:commit | Commit changes to workspace-shared from consuming repository (usage - task shared:dev:commit REPO_PATH=../ai-dev MESSAGE=“Update shared components”) |
| shared:dev:push | Push workspace-shared changes to remote repository (usage - task shared:dev:push REPO_PATH=../ai-dev) |
| shared:dev:release | Create a new release tag for workspace-shared (usage - task shared:dev:release REPO_PATH=../ai-dev TAG=v1.1.0 MESSAGE=“Release v1.1.0”) |
| shared:dev:test | Run tests for workspace-shared components (usage - task shared:dev:test REPO_PATH=../ai-dev) |
| shared:list | List all repositories with workspace-shared submodules |
| shared:pin | Pin workspace-shared submodule to specific version (usage - task shared:pin REPO_PATH=../ai-dev TAG=v1.0.0) |
| shared:setup | Add workspace-shared as submodule to a repository (usage - task shared:setup REPO_PATH=../ai-dev) |
| shared:status | Show workspace-shared submodule status across repositories (usage - task shared:status REPO_PATH=../ai-dev) |
| shared:test | Test workspace-shared management tasks functionality |
| shared:update | Update workspace-shared submodule to latest version (usage - task shared:update REPO_PATH=../ai-dev) |
| shared:validate | Validate workspace-shared submodule integrity (usage - task shared:validate REPO_PATH=../ai-dev) |
| workspace:bootstrap | Bootstrap workspace-root repository in code-server (one-time setup) |
| workspace:init | Initialize local workspace (usage - task workspace:init WS=codev) |
| workspace:install-tools | Install development tools (local execution - for Docker build) |
| workspace:install-tools-remote | Install development tools on remote code-server container (calls local task via kubectl exec) |
| workspace:shell | Get a shell in the code-server pod |
| workspace:status | Show code-server workspace status (local execution) |
| workspace:status-local | Show local workspace status |
| workspace:status-remote | Show code-server workspace status on remote container (calls local task via kubectl exec) |
| workspace:sync | Sync code-server workspaces and projects (local execution - reads from workspaces.yaml config) |
| workspace:sync-github | Sync GitHub repositories (requires SSH key to be added to GitHub) |
| workspace:sync-remote | Sync code-server workspaces and projects on remote container (calls local task via kubectl exec) |
| workspace:test-tools | Test installed development tools (local execution) |
| workspace:test-tools-remote | Test installed development tools on remote container (calls local task via kubectl exec) |
Best Practices
- Always check status first - Use
task statusor component-specific status tasks - Use the development workflow - Pause ArgoCD, apply directly, test, then resume
- Run tests before committing - Use appropriate test tasks for your changes
- Leverage existing tasks - Don’t reinvent commands that already exist
- Update tasks when needed - If you find yourself running the same commands repeatedly, add them to a Taskfile