mirror of https://github.com/coleam00/Archon synced 2026-04-21 21:47:53 +00:00

refactor(core): break up god function in command-handler (#742 )

* refactor(core): break up god function in command-handler

Extract handleWorktreeCommand, handleWorkflowCommand, handleRepoCommand,
and handleRepoRemoveCommand from the 1300-line handleCommand switch
statement. Add resolveRepoArg helper to eliminate duplication between
repo and repo-remove cases. handleCommand now contains ~200 lines of
routing logic only.

* fix: address review findings from PR #742

command-handler.ts:
- Replace fragile 'success' in discriminator with proper ResolveRepoArgResult
  discriminated union (ok: true/false) and fix misleading JSDoc
- Add missing error handling to worktree orphans, workflow cancel, workflow reload
- Fix isolation_env_id UUID used as filesystem path in worktree create/list/orphans
  (look up working_path from DB instead)
- Add cmd. domain prefix to all log events per CLAUDE.md convention
- Add identifier/isolationEnvId context to repo_switch_failed and worktree_remove_failed logs
- Capture isCurrentCodebase before mutation in handleRepoRemoveCommand
- Hoist duplicated workflowCwd computation in handleWorkflowCommand
- Remove stale (Phase 3D) comment marker

docs:
- Remove all /command-invoke references from CLAUDE.md, README.md,
  docs/architecture.md, and .claude/rules/orchestrator.md
- Update command list to match actual handleCommand cases
- Replace outdated routing examples with current AI router pattern

* refactor: remove MAX_WORKTREES_PER_CODEBASE limit

Worktree count is no longer restricted. Remove the constant, the
limit field from WorktreeStatusBreakdown, the limit_reached block
reason, formatWorktreeLimitMessage, and all associated tests.

* fix: address review findings — error handling, log prefixes, tests, docs

- Wrap workflow list discoverWorkflowsWithConfig in try/catch (was the
  only unprotected async call among workflow subcommands)
- Cast error to Error before logging in workflow cancel/status catch blocks
- Add cmd. domain prefix to all command-handler log events (12 events)
- Update worktree create test to use UUID isolation_env_id with DB lookup
- Add resolveRepoArg boundary tests (/repo 0, /repo N > count)
- Add worktree cleanup subcommand tests (merged, stale, invalid type)
- Add updateConversation assertion to repo-remove session test
- Fix stale docs: architecture.md command handler section, .claude → .archon
  paths, remove /command-invoke from commands-reference, fix github.md example

2026-03-25 11:01:03 +02:00

4 KiB

Raw Blame History

Commands Reference

All slash commands available in Archon. Type /help in any platform adapter (Web UI, Telegram, Slack, Discord, GitHub) to see this list.

Codebase Commands (Per-Project)

Command	Description
`/command-set <name> <path> [text]`	Register a command from file
`/load-commands <folder>`	Bulk load commands (recursive)
`/commands`	List registered commands

Note: Commands use relative paths (e.g., .archon/commands/plan.md)

Codebase Management

Command	Description
`/clone <repo-url>`	Clone repository
`/repos`	List repositories (numbered)
`/repo <#\|name> [pull]`	Switch repo (auto-loads commands)
`/repo-remove <#\|name>`	Remove repo and codebase record
`/getcwd`	Show working directory
`/setcwd <path>`	Set working directory

Tip: Use /repo for quick switching between cloned repos, /setcwd for manual paths.

Worktrees (Isolation)

Command	Description
`/worktree create <branch>`	Create isolated worktree
`/worktree list`	Show worktrees for this repo
`/worktree remove [--force]`	Remove current worktree
`/worktree cleanup merged\|stale`	Clean up worktrees
`/worktree orphans`	Show all worktrees from git

Workflows

Command	Description
`/workflow list`	Show available workflows
`/workflow reload`	Reload workflow definitions
`/workflow status`	Show running workflow details
`/workflow cancel`	Cancel running workflow

Note: Workflows are YAML files in .archon/workflows/

Session Management

Command	Description
`/status`	Show conversation state
`/reset`	Clear session completely
`/reset-context`	Reset AI context, keep worktree
`/help`	Show all commands

Setup

Command	Description
`/init`	Create `.archon` structure in current repo

Example Workflow (Telegram)

Clone a Repository

You: /clone https://github.com/user/my-project

Bot: Repository cloned successfully!

     Repository: my-project
     ✓ App defaults available at runtime

     Session reset - starting fresh on next message.

     You can now start asking questions about the code.

Note: Default commands and workflows are loaded at runtime and merged with repo-specific ones. Repo commands/workflows override app defaults by name. To disable defaults, set defaults.loadDefaultCommands: false or defaults.loadDefaultWorkflows: false in the repo's .archon/config.yaml.

Ask Questions Directly

You: What's the structure of this repo?

Bot: [Claude analyzes and responds...]

Create Custom Commands (Optional)

You: /init

Bot: Created .archon structure:
       .archon/
       ├── config.yaml
       └── commands/
           └── example.md

     Use /load-commands .archon/commands to register commands.

You can then create your own commands in .archon/commands/ and load them with /load-commands.

Check Status

You: /status

Bot: Platform: telegram
     AI Assistant: claude

     Codebase: my-project
     Repository: https://github.com/user/my-project

     Repository: my-project @ main

     Worktrees: 0/10

Work in Isolation with Worktrees

You: /worktree create feature-auth

Bot: Worktree created!

     Branch: feature-auth
     Path: feature-auth/

     This conversation now works in isolation.
     Run dependency install if needed (e.g., bun install).

Reset Session

You: /reset

Bot: Session cleared. Starting fresh on next message.

     Codebase configuration preserved.

Example Workflow (GitHub)

Create an issue or comment on an existing issue/PR:

@your-bot-name can you help me understand the authentication flow?

Bot responds with analysis. Continue the conversation:

@your-bot-name can you create a sequence diagram for this?

Bot maintains context and provides the diagram.

4 KiB Raw Blame History