@zelos/dev-cli

Development workflow automation CLI for Zelos projects. Automates GitHub issue management, git worktree creation, PLAN.md tracking, and PR workflows.

Features

• 🚀 Instant worktree creation - Start work on any issue in 10 seconds
• 📋 PLAN.md tracking - Automatic "In Progress" table updates
• 🔄 GitHub integration - Auto-comment on issues, create PRs
• ⚡ Fast PR workflow - Commit, push, and create PR in one command
• 🎯 Prioritized issue list - See what matters most
• ⚙️ Flexible configuration - Local project config + global user preferences

Installation

Global Installation (Recommended)

npm install -g @zelos/dev-cli
# or
pnpm add -g @zelos/dev-cli

Local Installation (Monorepo)

If you're working on the Zelos monorepo, it's already available:

pnpm work list

Quick Start

1. Initialize Configuration

# In your project root (must be a git repository)
work init

This creates .workrc.json with your project settings.

2. List Available Issues

work list                    # All open issues
work list --priority high    # High priority only
work list --area api         # API issues only

3. Start Work on an Issue

work start 147

This automatically:

• Fetches issue #147 from GitHub
• Generates branch name: feature/right-rail-147
• Creates worktree at ../zelos-right-rail-147
• Updates PLAN.md "In Progress" table
• Comments on GitHub issue

4. Finish Work and Create PR

cd ../zelos-right-rail-147
# ... make your changes ...
work finish

This automatically:

• Prompts for commit message
• Commits and pushes
• Creates GitHub PR
• Shows PR URL and next steps

Commands

work start <issue-number>

Start work on a GitHub issue.

Options:

• --no-comment - Skip GitHub issue comment
• --no-plan - Skip PLAN.md update
• --branch-name <name> - Override auto-generated branch name

Example:

work start 292
work start 148 --no-comment
work start 200 --branch-name hotfix/urgent-fix

work list

List all open GitHub issues, prioritized and grouped.

Options:

• --priority <level> - Filter by priority (critical, high, medium, low)
• --area <area> - Filter by area (api, web, db, infra)

Example:

work list
work list --priority high
work list --area api

work finish

Finish work: commit, push, create PR.

Options:

• --no-pr - Just commit and push (skip PR creation)
• --message <msg> - Provide commit message (skip interactive prompt)

Example:

work finish
work finish --message "feat: add athlete comparison (closes #145)"
work finish --no-pr

work init

Initialize .workrc.json configuration in your project.

Example:

work init

work config

Manage configuration.

Subcommands:

• work config list - Show current merged configuration
• work config get <key> - Get specific config value
• work config set <key> <value> - Set global config value

Example:

work config list
work config get githubRepo
work config set branchPrefix feat

Configuration

Configuration Priority

Configuration is loaded from multiple sources (higher priority overrides lower):

1. Environment variables (highest priority)

   • ZELOS_GITHUB_REPO
   • ZELOS_WORKTREE_PATH
   • ZELOS_PLAN_MD_PATH
   • ZELOS_BRANCH_PREFIX

2. Local project config: .workrc.json in git root

3. Global user config: ~/.config/zelos-cli/config.json

4. Built-in defaults (lowest priority)

Local Config Example (.workrc.json)

{
  "githubRepo": "avifenesh/zelos",
  "worktreePath": "../zelos-{name}",
  "planMdPath": "PLAN.md",
  "planMdTable": {
    "startLine": 27,
    "endLine": 31
  },
  "branchPrefix": "feature",
  "issueCommentTemplate": "🚀 Started work on this issue",
  "autoCommentIssue": true,
  "autoUpdatePlanMd": true
}

Global Config Example (~/.config/zelos-cli/config.json)

{
  "autoCommentIssue": false,
  "branchPrefix": "feat"
}

Authentication

GitHub authentication is required. The CLI auto-detects your token:

1. GITHUB_TOKEN environment variable
2. GitHub CLI (gh auth token)

If neither is found, run:

gh auth login

Workflow Example

Typical Development Flow

# 1. See what needs to be done
work list

# 2. Start work on an issue (10 seconds vs 10 minutes manually)
work start 147

# 3. Switch to the new worktree
cd ../zelos-right-rail-147

# 4. Start development
pnpm dev

# 5. Make changes...
#    Edit files, test, etc.

# 6. Finish and create PR (1 minute vs 5 minutes manually)
work finish

# 7. Follow PR workflow
#    Wait for CI, address reviews, merge

Quick Fix Flow

work start 148
cd ../zelos-video-timestamps-148
# ... make quick fix ...
work finish --message "fix: video timestamp parsing (closes #148)"

Features

Automatic Branch Naming

Branches are auto-generated from issue titles:

• Issue #292: "Stats Entry UI for Athletes" → feature/stats-entry-292
• Issue #148: "Fix: Video Timestamps" → feature/fix-video-148

Algorithm:

• Extract first 4 meaningful words
• Exclude common words (a, an, the, for, to, ui, ux)
• Kebab-case formatting
• Append issue number

PLAN.md Integration

Automatically maintains the "In Progress" table in your PLAN.md:

### 🔄 In Progress

| Issue | Task | Branch |
|-------|------|--------|
| #147  | Right Rail Enhancement | `feature/right-rail-147` |

Error Handling

The CLI gracefully handles common errors:

• Issue not found → Suggests work list
• Worktree already exists → Clear error message with resolution
• GitHub rate limit → Shows reset time
• Network errors → Retries 3x with exponential backoff
• Not in git repo → Clear error message

Development

Local Development (Monorepo)

# Build the package
cd packages/cli
pnpm build

# Link globally for testing
pnpm link-global

# Now use from anywhere
cd ../zelos-dx
work list

# Unlink when done
cd packages/cli
pnpm unlink-global

Watch Mode

cd packages/cli
pnpm dev    # Auto-rebuild on file changes

Troubleshooting

"GitHub token not found"

gh auth login
# OR
export GITHUB_TOKEN=<your-token>

"Not in a git repository"

The CLI must be run from within a git repository. Ensure you're in your project directory.

"GitHub repository not configured"

Run work init to create .workrc.json, or set:

export ZELOS_GITHUB_REPO=owner/repo

"Command not found: work"

If installed globally:

npm install -g @zelos/dev-cli

If using locally in monorepo:

cd packages/cli
pnpm link-global

Architecture

Built with:

• Language: TypeScript (compiled to JavaScript)
• CLI Framework: Commander v12
• GitHub API: Octokit (@octokit/rest)
• UI: Chalk (colors), Ora (spinners), Enquirer (prompts)
• Process Execution: Execa v8

Package Structure:

packages/cli/
├── src/
│   ├── cli.ts              # Main entry point
│   ├── commands/           # Command implementations
│   ├── lib/                # Core libraries
│   └── index.ts            # Public API exports
├── dist/                   # Compiled output
├── tests/                  # Unit tests
└── package.json

Contributing

This package is open source! Contributions welcome.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a PR

License

MIT License - see LICENSE file for details.

Links

• Repository: https://github.com/avifenesh/zelos
• Issues: https://github.com/avifenesh/zelos/issues
• npm: https://www.npmjs.com/package/@zelos/dev-cli

Made with ❤️ for developer productivity