From 61cbf2bdedbaec393f8b8ae3bee7c0035251fcf8 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 18:34:49 +0000 Subject: [PATCH] docs: add ai command docs, update CLI structure - Create docs/cmd/ai/index.md with full task management documentation - Add ai command to main docs/cmd/index.md command list - Update docs/cmd/dev/index.md to point to ai for task commands - Update TODO.md to reflect current documentation state Task commands (tasks, task, task:update, task:complete, task:commit, task:pr) have moved from dev to ai package. Co-Authored-By: Claude Opus 4.5 --- docs/cmd/TODO.md | 238 ++++++++++++++++------------------- docs/cmd/ai/index.md | 282 ++++++++++++++++++++++++++++++++++++++++++ docs/cmd/dev/index.md | 190 ++-------------------------- docs/cmd/index.md | 6 +- 4 files changed, 403 insertions(+), 313 deletions(-) create mode 100644 docs/cmd/ai/index.md diff --git a/docs/cmd/TODO.md b/docs/cmd/TODO.md index 062f5ffd..b2579ade 100644 --- a/docs/cmd/TODO.md +++ b/docs/cmd/TODO.md @@ -2,147 +2,125 @@ Commands and subcommands that need documentation. +## Summary + +| Package | CLI Commands | Documented | Coverage | Status | +|---------|--------------|------------|----------|--------| +| ai | 10 | 10 | 100% | ✓ Complete | +| build | 4 | 2 | 50% | Needs work | +| ci | 4 | 4 | 100% | ✓ Complete | +| dev | 21 | 21 | 100% | ✓ Complete | +| docs | 3 | 3 | 100% | ✓ Complete | +| doctor | 1 | 1 | 100% | ✓ Complete | +| go | 14 | 14 | 100% | ✓ Complete | +| php | 20 | 1 | 5% | Needs work | +| pkg | 5 | 2 | 40% | Needs work | +| sdk | 3 | 1 | 33% | Needs work | +| setup | 1 | 1 | 100% | ✓ Complete | +| test | 1 | 1 | 100% | ✓ Complete | +| vm | 8 | 2 | 25% | Needs work | + ## Missing Documentation -| Command | Subcommand | Status | -|---------|------------|--------| -| dev | health | Missing | -| dev | commit | Missing | -| dev | push | Missing | -| dev | pull | Missing | -| dev | issues | Missing | -| dev | reviews | Missing | -| dev | ci | Missing | -| dev | impact | Missing | -| dev | api | Missing | -| dev | api sync | Missing | -| dev | sync | Missing | -| dev | tasks | Missing | -| dev | task | Missing | -| dev | task:update | Missing | -| dev | task:complete | Missing | -| dev | task:commit | Missing | -| dev | task:pr | Missing | -| dev | install | Missing | -| dev | boot | Missing | -| dev | stop | Missing | -| dev | status | Missing | -| dev | shell | Missing | -| dev | serve | Missing | -| dev | test | Missing | -| dev | claude | Missing | -| dev | update | Missing | -| go | work sync | Missing | -| go | work init | Missing | -| go | work use | Missing | -| go | mod tidy | Missing | -| go | mod download | Missing | -| go | mod verify | Missing | -| go | mod graph | Missing | -| php | dev | Missing | -| php | logs | Missing | -| php | stop | Missing | -| php | status | Missing | -| php | ssl | Missing | -| php | build | Missing | -| php | serve | Missing | -| php | shell | Missing | -| php | test | Missing | -| php | fmt | Missing | -| php | analyse | Missing | -| php | packages | Missing | -| php | packages link | Missing | -| php | packages unlink | Missing | -| php | packages update | Missing | -| php | packages list | Missing | -| php | deploy | Missing | -| php | deploy:status | Missing | -| php | deploy:rollback | Missing | -| php | deploy:list | Missing | -| build | from-path | Missing | -| build | pwa | Missing | -| ci | - | Missing (only has subcommands) | -| sdk | diff | Missing | -| sdk | validate | Missing | -| pkg | install | Missing | -| pkg | list | Missing | -| pkg | update | Missing | -| pkg | outdated | Missing | -| vm | run | Missing | -| vm | ps | Missing | -| vm | stop | Missing | -| vm | logs | Missing | -| vm | exec | Missing | -| vm | templates show | Missing | -| vm | templates vars | Missing | -| docs | sync | Missing | -| docs | list | Missing | +### build -## Needs Update +| Command | Status | +|---------|--------| +| build from-path | Missing | +| build pwa | Missing | -| Command | Issue | -|---------|-------| -| build/sdk | Documentation exists but command has been moved to `build sdk` | -| go/work | Index exists but subcommands (sync, init, use) are undocumented | -| go/mod | Index exists but subcommands (tidy, download, verify, graph) are undocumented | -| vm/templates | Index exists but subcommands (show, vars) are undocumented | -| pkg/search | Index exists but may need updating with new flags | +### php (subcommand detail pages) -## Documentation Structure Notes +All covered in main index.md but no individual pages: -The following commands have complete documentation: -- `test` - /Users/snider/Code/host-uk/core/docs/cmd/test/index.md -- `doctor` - /Users/snider/Code/host-uk/core/docs/cmd/doctor/index.md -- `setup` - /Users/snider/Code/host-uk/core/docs/cmd/setup/index.md -- `dev/work` - /Users/snider/Code/host-uk/core/docs/cmd/dev/work/index.md -- `dev` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/dev/index.md -- `go` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/go/index.md -- `go/test` - /Users/snider/Code/host-uk/core/docs/cmd/go/test/index.md -- `go/cov` - /Users/snider/Code/host-uk/core/docs/cmd/go/cov/index.md -- `go/fmt` - /Users/snider/Code/host-uk/core/docs/cmd/go/fmt/index.md -- `go/lint` - /Users/snider/Code/host-uk/core/docs/cmd/go/lint/index.md -- `go/install` - /Users/snider/Code/host-uk/core/docs/cmd/go/install/index.md -- `go/mod` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/go/mod/index.md -- `go/work` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/go/work/index.md -- `ci/init` - /Users/snider/Code/host-uk/core/docs/cmd/ci/init/index.md -- `ci/changelog` - /Users/snider/Code/host-uk/core/docs/cmd/ci/changelog/index.md -- `ci/version` - /Users/snider/Code/host-uk/core/docs/cmd/ci/version/index.md -- `build` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/build/index.md -- `build/sdk` - /Users/snider/Code/host-uk/core/docs/cmd/build/sdk/index.md -- `sdk` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/sdk/index.md -- `pkg` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/pkg/index.md -- `pkg/search` - /Users/snider/Code/host-uk/core/docs/cmd/pkg/search/index.md -- `vm` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/vm/index.md -- `vm/templates` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/vm/templates/index.md -- `php` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/php/index.md -- `docs` (parent) - /Users/snider/Code/host-uk/core/docs/cmd/docs/index.md +| Command | Status | +|---------|--------| +| php dev | Missing (covered in index) | +| php logs | Missing (covered in index) | +| php stop | Missing (covered in index) | +| php status | Missing (covered in index) | +| php ssl | Missing (covered in index) | +| php build | Missing (covered in index) | +| php serve | Missing (covered in index) | +| php shell | Missing (covered in index) | +| php test | Missing (covered in index) | +| php fmt | Missing (covered in index) | +| php analyse | Missing (covered in index) | +| php packages link | Missing | +| php packages unlink | Missing | +| php packages update | Missing | +| php packages list | Missing | +| php deploy | Missing | +| php deploy:status | Missing | +| php deploy:rollback | Missing | +| php deploy:list | Missing | -## Priority Recommendations +### pkg -High priority (commonly used commands): -1. `dev` subcommands (health, commit, push, pull, issues, reviews, ci, impact) -2. `php` subcommands (dev, build, test, fmt, packages) -3. `go/mod` subcommands (tidy, download, verify) -4. `go/work` subcommands (sync, init, use) -5. `vm` core commands (run, ps, stop, logs) +| Command | Status | +|---------|--------| +| pkg install | Missing | +| pkg list | Missing | +| pkg update | Missing | +| pkg outdated | Missing | -Medium priority: -1. `dev` task management commands -2. `dev` dev environment commands (install, boot, stop, status, shell) -3. `sdk` validation commands -4. `pkg` package management commands -5. `php` deployment commands -6. `build` alternative builders (from-path, pwa) +### sdk -Low priority: -1. `dev` advanced commands (api sync, claude, update) -2. `vm/templates` subcommands -3. `docs` management commands +| Command | Status | +|---------|--------| +| sdk diff | Missing | +| sdk validate | Missing | -## Issues Found +### vm -- There appears to be duplicate documentation under `/Users/snider/Code/host-uk/core/docs/cmd/docs/cmd/` which mirrors the main command structure. This should be cleaned up. -- The `ci` parent command has no index.md, only subcommand documentation exists. -- Many parent commands (dev, go, php, etc.) have good overview documentation but are missing subcommand details. +| Command | Status | +|---------|--------| +| vm run | Missing | +| vm ps | Missing | +| vm stop | Missing | +| vm logs | Missing | +| vm exec | Missing | +| vm templates show | Missing | +| vm templates vars | Missing | + +## Recently Completed + +- ✓ ai (all commands documented in index.md) +- ✓ dev (health, commit, push, pull, issues, reviews, ci, impact) +- ✓ go/mod (tidy, download, verify, graph) +- ✓ go/work (sync, init, use) +- ✓ ci (init, changelog, version) + +## Documentation Structure + +All documented packages follow this structure: +``` +/docs/cmd/{package}/ +├── index.md (main command overview) +├── example.md (optional usage examples) +└── {subcommand}/ + ├── index.md (subcommand docs) + └── example.md (optional examples) +``` + +## Priority + +### High +1. `php` subcommands - Most commonly used +2. `vm` core commands - Important for dev environment + +### Medium +3. `pkg` package management commands +4. `sdk` validation commands +5. `build` legacy commands (from-path, pwa) + +### Low +6. `vm/templates` subcommands + +## Notes + +- The `ai` package is new and contains task management commands previously documented under `dev` +- The `dev` index.md includes task command docs that now refer to the `ai` package +- Many packages have comprehensive index.md files but lack individual subcommand pages Last verified: 2026-01-29 diff --git a/docs/cmd/ai/index.md b/docs/cmd/ai/index.md new file mode 100644 index 00000000..507168ac --- /dev/null +++ b/docs/cmd/ai/index.md @@ -0,0 +1,282 @@ +# core ai + +AI agent task management and Claude Code integration. + +## Task Management Commands + +| Command | Description | +|---------|-------------| +| `tasks` | List available tasks from core-agentic | +| `task` | View task details or auto-select | +| `task:update` | Update task status or progress | +| `task:complete` | Mark task as completed or failed | +| `task:commit` | Create git commit with task reference | +| `task:pr` | Create GitHub PR linked to task | + +## Claude Integration + +| Command | Description | +|---------|-------------| +| `claude run` | Run Claude Code in current directory | +| `claude config` | Manage Claude configuration | + +--- + +## Configuration + +Task commands load configuration from: +1. Environment variables (`AGENTIC_TOKEN`, `AGENTIC_BASE_URL`) +2. `.env` file in current directory +3. `~/.core/agentic.yaml` + +--- + +## ai tasks + +List available tasks from core-agentic. + +```bash +core ai tasks [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--status` | Filter by status (`pending`, `in_progress`, `completed`, `blocked`) | +| `--priority` | Filter by priority (`critical`, `high`, `medium`, `low`) | +| `--labels` | Filter by labels (comma-separated) | +| `--project` | Filter by project | +| `--limit` | Max number of tasks to return (default: 20) | + +### Examples + +```bash +# List all pending tasks +core ai tasks + +# Filter by status and priority +core ai tasks --status pending --priority high + +# Filter by labels +core ai tasks --labels bug,urgent +``` + +--- + +## ai task + +View task details or auto-select a task. + +```bash +core ai task [task-id] [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--auto` | Auto-select highest priority pending task | +| `--claim` | Claim the task after showing details | +| `--context` | Show gathered context for AI collaboration | + +### Examples + +```bash +# Show task details +core ai task abc123 + +# Show and claim +core ai task abc123 --claim + +# Show with context +core ai task abc123 --context + +# Auto-select highest priority pending task +core ai task --auto +``` + +--- + +## ai task:update + +Update a task's status, progress, or notes. + +```bash +core ai task:update [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--status` | New status (`pending`, `in_progress`, `completed`, `blocked`) | +| `--progress` | Progress percentage (0-100) | +| `--notes` | Notes about the update | + +### Examples + +```bash +# Set task to in progress +core ai task:update abc123 --status in_progress + +# Update progress with notes +core ai task:update abc123 --progress 50 --notes 'Halfway done' +``` + +--- + +## ai task:complete + +Mark a task as completed with optional output and artifacts. + +```bash +core ai task:complete [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--output` | Summary of the completed work | +| `--failed` | Mark the task as failed | +| `--error` | Error message if failed | + +### Examples + +```bash +# Complete successfully +core ai task:complete abc123 --output 'Feature implemented' + +# Mark as failed +core ai task:complete abc123 --failed --error 'Build failed' +``` + +--- + +## ai task:commit + +Create a git commit with a task reference and co-author attribution. + +```bash +core ai task:commit [flags] +``` + +Commit message format: +``` +feat(scope): description + +Task: #123 +Co-Authored-By: Claude +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `-m`, `--message` | Commit message (without task reference) | +| `--scope` | Scope for the commit type (e.g., `auth`, `api`, `ui`) | +| `--push` | Push changes after committing | + +### Examples + +```bash +# Commit with message +core ai task:commit abc123 --message 'add user authentication' + +# With scope +core ai task:commit abc123 -m 'fix login bug' --scope auth + +# Commit and push +core ai task:commit abc123 -m 'update docs' --push +``` + +--- + +## ai task:pr + +Create a GitHub pull request linked to a task. + +```bash +core ai task:pr [flags] +``` + +Requires the GitHub CLI (`gh`) to be installed and authenticated. + +### Flags + +| Flag | Description | +|------|-------------| +| `--title` | PR title (defaults to task title) | +| `--base` | Base branch (defaults to main) | +| `--draft` | Create as draft PR | +| `--labels` | Labels to add (comma-separated) | + +### Examples + +```bash +# Create PR with defaults +core ai task:pr abc123 + +# Custom title +core ai task:pr abc123 --title 'Add authentication feature' + +# Draft PR with labels +core ai task:pr abc123 --draft --labels 'enhancement,needs-review' + +# Target different base branch +core ai task:pr abc123 --base develop +``` + +--- + +## ai claude + +Claude Code integration commands. + +### ai claude run + +Run Claude Code in the current directory. + +```bash +core ai claude run +``` + +### ai claude config + +Manage Claude configuration. + +```bash +core ai claude config +``` + +--- + +## Workflow Example + +```bash +# 1. List available tasks +core ai tasks --status pending + +# 2. Auto-select and claim a task +core ai task --auto --claim + +# 3. Work on the task... + +# 4. Update progress +core ai task:update abc123 --progress 75 + +# 5. Commit with task reference +core ai task:commit abc123 -m 'implement feature' + +# 6. Create PR +core ai task:pr abc123 + +# 7. Mark complete +core ai task:complete abc123 --output 'Feature implemented and PR created' +``` + +## See Also + +- [dev](../dev/) - Multi-repo workflow commands +- [Claude Code documentation](https://claude.ai/code) diff --git a/docs/cmd/dev/index.md b/docs/cmd/dev/index.md index 09dab82f..676103ca 100644 --- a/docs/cmd/dev/index.md +++ b/docs/cmd/dev/index.md @@ -20,14 +20,16 @@ Multi-repo workflow and portable development environment. ## Task Management Commands +> **Note:** Task management commands have moved to [`core ai`](../ai/). + | Command | Description | |---------|-------------| -| `tasks` | List available tasks from core-agentic | -| `task` | Show task details or auto-select a task | -| `task:update` | Update task status or progress | -| `task:complete` | Mark a task as completed | -| `task:commit` | Auto-commit changes with task reference | -| `task:pr` | Create a pull request for a task | +| [`ai tasks`](../ai/) | List available tasks from core-agentic | +| [`ai task`](../ai/) | Show task details or auto-select a task | +| [`ai task:update`](../ai/) | Update task status or progress | +| [`ai task:complete`](../ai/) | Mark a task as completed | +| [`ai task:commit`](../ai/) | Auto-commit changes with task reference | +| [`ai task:pr`](../ai/) | Create a pull request for a task | ## Dev Environment Commands @@ -412,181 +414,7 @@ core dev sync This command scans the `pkg` directory for services and ensures that the top-level public API for each service is in sync with its internal implementation. It automatically generates the necessary Go files with type aliases. -## Task Management Commands - -The task commands integrate with the core-agentic service for AI-powered task management. - -### Configuration - -Task commands load configuration from: -1. Environment variables (`AGENTIC_TOKEN`, `AGENTIC_BASE_URL`) -2. `.env` file in current directory -3. `~/.core/agentic.yaml` - -### dev tasks - -List available tasks from core-agentic. - -```bash -core dev tasks [flags] -``` - -#### Flags - -| Flag | Description | -|------|-------------| -| `--status` | Filter by status (`pending`, `in_progress`, `completed`, `blocked`) | -| `--priority` | Filter by priority (`critical`, `high`, `medium`, `low`) | -| `--labels` | Filter by labels (comma-separated) | -| `--project` | Filter by project | -| `--limit` | Max number of tasks to return (default: 20) | - -#### Examples - -```bash -core dev tasks -core dev tasks --status pending --priority high -core dev tasks --labels bug,urgent -``` - -### dev task - -Show task details or auto-select a task. - -```bash -core dev task [task-id] [flags] -``` - -#### Flags - -| Flag | Description | -|------|-------------| -| `--auto` | Auto-select highest priority pending task | -| `--claim` | Claim the task after showing details | -| `--context` | Show gathered context for AI collaboration | - -#### Examples - -```bash -# Show task details -core dev task abc123 - -# Show and claim -core dev task abc123 --claim - -# Show with context -core dev task abc123 --context - -# Auto-select highest priority pending task -core dev task --auto -``` - -### dev task:update - -Update a task's status, progress, or notes. - -```bash -core dev task:update [flags] -``` - -#### Flags - -| Flag | Description | -|------|-------------| -| `--status` | New status (`pending`, `in_progress`, `completed`, `blocked`) | -| `--progress` | Progress percentage (0-100) | -| `--notes` | Notes about the update | - -#### Examples - -```bash -core dev task:update abc123 --status in_progress -core dev task:update abc123 --progress 50 --notes 'Halfway done' -``` - -### dev task:complete - -Mark a task as completed with optional output and artifacts. - -```bash -core dev task:complete [flags] -``` - -#### Flags - -| Flag | Description | -|------|-------------| -| `--output` | Summary of the completed work | -| `--failed` | Mark the task as failed | -| `--error` | Error message if failed | - -#### Examples - -```bash -core dev task:complete abc123 --output 'Feature implemented' -core dev task:complete abc123 --failed --error 'Build failed' -``` - -### dev task:commit - -Create a git commit with a task reference and co-author attribution. - -```bash -core dev task:commit [flags] -``` - -Commit message format: -``` -feat(scope): description - -Task: #123 -Co-Authored-By: Claude -``` - -#### Flags - -| Flag | Description | -|------|-------------| -| `-m`, `--message` | Commit message (without task reference) | -| `--scope` | Scope for the commit type (e.g., `auth`, `api`, `ui`) | -| `--push` | Push changes after committing | - -#### Examples - -```bash -core dev task:commit abc123 --message 'add user authentication' -core dev task:commit abc123 -m 'fix login bug' --scope auth -core dev task:commit abc123 -m 'update docs' --push -``` - -### dev task:pr - -Create a GitHub pull request linked to a task. - -```bash -core dev task:pr [flags] -``` - -Requires the GitHub CLI (`gh`) to be installed and authenticated. - -#### Flags - -| Flag | Description | -|------|-------------| -| `--title` | PR title (defaults to task title) | -| `--base` | Base branch (defaults to main) | -| `--draft` | Create as draft PR | -| `--labels` | Labels to add (comma-separated) | - -#### Examples - -```bash -core dev task:pr abc123 -core dev task:pr abc123 --title 'Add authentication feature' -core dev task:pr abc123 --draft --labels 'enhancement,needs-review' -core dev task:pr abc123 --base develop -``` - ## See Also - [work](work/) - Multi-repo workflow commands (`core dev work`, `core dev health`, etc.) +- [ai](../ai/) - Task management commands (`core ai tasks`, `core ai task`, etc.) diff --git a/docs/cmd/index.md b/docs/cmd/index.md index 03ad5df9..d6d6430e 100644 --- a/docs/cmd/index.md +++ b/docs/cmd/index.md @@ -6,17 +6,19 @@ Unified interface for Go/PHP development, multi-repo management, and deployment. | Command | Description | |---------|-------------| +| [ai](ai/) | AI agent task management and Claude integration | | [go](go/) | Go development tools | | [php](php/) | Laravel/PHP development tools | | [build](build/) | Build projects | | [ci](ci/) | Publish releases | -| [sdk](sdk/) | SDK generation and validation | +| [sdk](sdk/) | SDK validation and compatibility | | [dev](dev/) | Multi-repo workflow + dev environment | | [pkg](pkg/) | Package management | | [vm](vm/) | LinuxKit VM management | | [docs](docs/) | Documentation management | -| [setup](setup/) | Clone repos or setup repository | +| [setup](setup/) | Clone repos from registry | | [doctor](doctor/) | Check environment | +| [test](test/) | Run Go tests with coverage | ## Installation