Enhance CLI with project workflows, feature flags, and documentation updates

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,11 @@
 blank_issues_enabled: false
 contact_links:
   - name: Security policy
-    url: https://github.com/backslash-ux/plane-cli/blob/main/SECURITY.md
+    url: https://github.com/backslash-ux/plane-cli-cli/blob/main/SECURITY.md
     about: Report suspected vulnerabilities privately instead of opening a public issue.
   - name: Contributing guide
-    url: https://github.com/backslash-ux/plane-cli/blob/main/CONTRIBUTING.md
+    url: https://github.com/backslash-ux/plane-cli-cli/blob/main/CONTRIBUTING.md
     about: Review contribution expectations, quality gates, and documentation requirements first.
   - name: Existing issues
-    url: https://github.com/backslash-ux/plane-cli/issues
+    url: https://github.com/backslash-ux/plane-cli-cli/issues
     about: Check open issues and feature requests before filing a new one.

.gitignore

@@ -2,11 +2,12 @@ node_modules/
 dist/
 .env
 *.env
+.plane/
 
 # Local AI/editor customization files
 .github/copilot-instructions.md
 .github/instructions/
 .github/prompts/
 .github/agents/
-.vscode/docs/
+.vscode/
 

.husky/pre-commit

@@ -1,7 +1,16 @@
+# Locate bun - git hooks run with a stripped PATH that often omits ~/.bun/bin
+BUN=$(command -v bun 2>/dev/null \
+  || command -v "$HOME/.bun/bin/bun" 2>/dev/null \
+  || echo "")
+if [ -z "$BUN" ]; then
+  echo "husky: bun not found in PATH or ~/.bun/bin – please install bun or add it to your PATH" >&2
+  exit 1
+fi
+
 # Check file sizes
 echo "Checking file sizes..."
-bun scripts/check-file-size.ts
+"$BUN" scripts/check-file-size.ts
 
 # Check test coverage
 echo "Checking test coverage..."
-bun run test:coverage:check
+"$BUN" scripts/check-coverage.ts

AGENTS.md

@@ -51,4 +51,39 @@ Before making non-trivial changes:
 - Keep public documentation presentable and accurate.
 - Use [CHANGELOG.md](./CHANGELOG.md) for notable user-facing changes.
 - Follow [docs/RELEASING.md](./docs/RELEASING.md) for release workflow expectations.
-- Respect [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and [SECURITY.md](./SECURITY.md).
+- Respect [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) and [SECURITY.md](./SECURITY.md).
+
+## Known Deployment Compatibility
+
+The CLI has been validated against a real Plane instance. Be aware of these deployment-dependent behaviors when developing or testing:
+
+- **Pages**: The CLI targets the project-page API surface. Plane also has a separate workspace wiki page surface that the CLI does not cover. Both may return 404 on some deployments even when the project feature flag is enabled.
+- **Worklogs**: Time tracking is a Pro-plan feature. Non-Pro deployments will not expose worklog API endpoints.
+- **Feature gating**: The CLI returns explicit compatibility errors (not raw 404s) when a project feature is flagged on but the backing API route is absent.
+
+<!-- plane-cli local project context start -->
+## Plane Project Context
+This directory is scoped to Plane project PLANECLI (Plane CLI).
+
+When working as an AI agent in this directory:
+- Read `./.plane/project-context.json` before planning or applying Plane project changes.
+- Reuse the existing states, labels, and estimate points in that snapshot instead of creating duplicates.
+- Respect the feature flags in that snapshot before using cycles, modules, pages, intake, or estimates.
+- Prefer the `plane` CLI from this repository root for Plane project work instead of direct API calls.
+- Use `@current` as the default project selector once local init has been run.
+- If the shell may contain inherited `PLANE_*` variables, clear them before relying on `./.plane/config.json`.
+
+Common agent commands:
+
+```sh
+unset PLANE_HOST PLANE_WORKSPACE PLANE_API_TOKEN PLANE_PROJECT
+plane projects current
+plane issues list @current
+plane issue get PLANECLI-12
+plane issue update --state started PLANECLI-12
+```
+
+- Rerun `plane init --local` from this directory whenever the Plane project configuration changes so this context stays current.
+
+This section is managed by `plane-cli` and is updated by `plane init --local`.
+<!-- plane-cli local project context end -->

CHANGELOG.md

@@ -13,5 +13,18 @@ Earlier project history may predate this file.
 - Public open-source repository baseline with contributor, governance, security, architecture, and release documentation.
 - GitHub issue and pull request templates plus issue intake routing.
 - Stricter repository quality gates covering formatting, file-size limits, and coverage thresholds.
-- Fork-specific package identity and public metadata alignment under `@backslash-ux/plane`.
-- A versioned root `AGENTS.md` file that provides baseline context for AI coding agents contributing to the repository.
+- Fork-specific package identity and public metadata alignment under `@backslash-ux/plane-cli`.
+- A versioned root `AGENTS.md` file that provides baseline context for AI coding agents contributing to the repository.
+- `plane labels delete` and `plane modules delete` cleanup commands.
+
+### Changed
+
+- Tightened published CLI documentation so README and SKILL examples match the validated command grammar, identifier semantics, and deployment-compatibility behavior.
+- Updated compatibility notes in README and SKILL to document confirmed page and worklog deployment dependencies.
+
+### Validated
+
+- Full live test sweep completed against a real Plane instance. All core CLI workflows exercised: init (global, local, alias), project resolution, issue CRUD with rich options, comments, links, activity, cycles, modules, intake mutations, states, labels, members, and structured output.
+- Confirmed the CLI's project-page endpoint routes are correct; both page API surfaces (project pages and workspace wiki pages) return 404 on some deployments regardless of feature flags.
+- Confirmed worklogs are a Pro-plan-gated feature; the CLI returns explicit compatibility errors on non-Pro deployments.
+- Added and validated first-class CLI cleanup commands for label delete and module delete.

README.md

@@ -1,6 +1,6 @@
 # plane
 
-[![CI](https://github.com/backslash-ux/plane-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/backslash-ux/plane-cli/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![CI](https://github.com/backslash-ux/plane-cli-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/backslash-ux/plane-cli-cli/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
 CLI for the [Plane](https://plane.so) project management API.
 
@@ -31,57 +31,101 @@ This repository is a fork of [aaronshaf/plane-cli](https://github.com/aaronshaf/
 
 ```bash
 curl -fsSL https://bun.sh/install | bash
-bun install -g @backslash-ux/plane
+bun install -g @backslash-ux/plane-cli
 ```
 
 ## Setup
 
 ```bash
-plane init
+plane init -g
 ```
 
-Prompts for your Plane host, workspace slug, and API token. Saves to `~/.config/plane/config.json` (mode 0600). Safe to re-run.
+Prompts for your Plane host, workspace, and API token. Global setup saves to `~/.config/plane/config.json` (mode 0600). Safe to re-run.
+It also offers an optional current-project selection so repeated project-scoped commands can reuse the same context.
+
+For path-local overrides in the current project directory:
+
+```bash
+plane init --local
+plane . init
+```
+
+Local setup writes `./.plane/config.json`. When the CLI runs, it resolves config with this precedence:
+
+```text
+environment variables > nearest .plane/config.json > ~/.config/plane/config.json
+```
+
+The local config is discovered from the current working directory upward, so a config written at the repo root applies inside nested folders unless a deeper `.plane/config.json` overrides it.
+When you run `plane init --local`, the CLI also reads the project's feature flags from Plane and reports which project-scoped features are actually enabled. Cycles, modules, pages, and intake commands return explicit feature-disabled errors when the project has them turned off.
+It also writes `.plane/project-context.json`, a machine-readable helper snapshot of the project's existing states, labels, and estimate points so agents can reuse what already exists instead of inventing duplicates.
+If `AGENTS.md` already exists in that directory, `plane init --local` appends a managed Plane project context section at the bottom without removing the existing content. If it does not exist, the CLI creates it. The managed section points agents at `.plane/project-context.json`, tells them to prefer the repo-local `plane` CLI for Plane work, and includes a small command pattern for clearing inherited `PLANE_*` overrides before using the local config.
 
 You can also use environment variables (override saved config):
 
 ```
 PLANE_API_TOKEN=...
 PLANE_HOST=https://plane.so
 PLANE_WORKSPACE=myworkspace
+PLANE_PROJECT=PROJ               # optional saved-project override
 ```
 
+To persist a current project after setup:
+
+```bash
+plane projects list
+plane projects use PROJ
+plane projects use PROJ --local
+plane projects use PROJ --global
+plane projects current
+```
+
+When a local config is active in the current path, `plane projects use PROJ` writes there by default; otherwise it writes to global config. Once a current project is saved, list-style commands such as `plane issues list`, `plane cycles list`, `plane modules list`, `plane pages list`, `plane states list`, `plane labels list`, and `plane intake list` can omit the project argument. Other project-scoped commands can use `@current` instead of repeating the identifier.
+
+Project-scoped feature availability still depends on the target Plane project. On deployments where a feature is flagged on but the backing API is unavailable, the CLI returns an explicit compatibility error instead of a raw backend `404`.
+
+**Known deployment dependencies:**
+
+- **Pages**: The CLI targets the project-page API surface (`/projects/{id}/pages/`). Some Plane deployments do not expose page endpoints even when the project feature flag is present. Additionally, Plane has a separate workspace wiki page surface that the CLI does not cover.
+- **Worklogs**: Time tracking is a Pro-plan feature. Non-Pro deployments will return compatibility errors for worklog commands.
+
 ## Common Commands
 
 ```bash
 # Projects
 plane projects list
+plane projects use PROJ
+plane projects use PROJ --local
+plane projects current
 
 # Issues
+plane issues list
 plane issues list PROJ
 plane issues list PROJ --state started
 plane issue get PROJ-29
 plane issue create PROJ "Title"
-plane issue update PROJ-29 --state done --priority high
+plane issue create @current "Title"
+plane issue update --state completed --priority high PROJ-29
 plane issue delete PROJ-29
 
 # Comments
 plane issue comments list PROJ-29
-plane issue comments add PROJ-29 "text"
+plane issue comment PROJ-29 "text"
 plane issue comments update PROJ-29 COMMENT_ID "new text"
 plane issue comments delete PROJ-29 COMMENT_ID
 
 # Links
 plane issue link list PROJ-29
-plane issue link add PROJ-29 https://example.com "title"
+plane issue link add --title "title" PROJ-29 https://example.com
 plane issue link remove PROJ-29 LINK_ID
 
 # Activity
 plane issue activity PROJ-29
 
 # Worklogs
 plane issue worklogs list PROJ-29
-plane issue worklogs add PROJ-29 --duration 90
-plane issue worklogs add PROJ-29 --duration 30 --description "standup"
+plane issue worklogs add PROJ-29 90
+plane issue worklogs add --description "standup" PROJ-29 30
 
 # Cycles
 plane cycles list PROJ
@@ -90,9 +134,10 @@ plane cycles issues add PROJ CYCLE_ID PROJ-29
 
 # Modules
 plane modules list PROJ
+plane modules delete PROJ MODULE_ID
 plane modules issues list PROJ MODULE_ID
 plane modules issues add PROJ MODULE_ID PROJ-29
-plane modules issues remove PROJ MODULE_ID PROJ-29
+plane modules issues remove PROJ MODULE_ID MODULE_ISSUE_ID
 
 # Intake
 plane intake list PROJ
@@ -106,7 +151,8 @@ plane pages get PROJ PAGE_ID
 # States, labels, members
 plane states list PROJ
 plane labels list PROJ
-plane members list PROJ
+plane labels delete PROJ bug
+plane members list
 ```
 
 Project identifiers: short strings like `PROJ`, `WEB`. Issue refs: `PROJ-29`, `WEB-5`.
@@ -127,16 +173,31 @@ plane issues list PROJ --xml
 plane cycles list PROJ --json
 ```
 
+## Command Notes
+
+- `plane issue update` expects flags before the issue ref, for example `plane issue update --state completed PROJ-29`.
+- `--description` for issue and page create or update commands is sent through to Plane as HTML in `description_html`.
+- `plane issue link add` accepts an optional link title via `--title`.
+- `plane labels delete` accepts either the label UUID or the exact label name returned by `plane labels list`.
+- `plane modules delete` accepts either the module UUID or the exact module name returned by `plane modules list`.
+- `plane modules issues remove` expects the module-issue identifier returned by `plane modules issues list`, not an issue ref.
+- `plane members list` is workspace-scoped and does not take a project argument.
+
+## Compatibility Notes
+
+- `plane init --local` reports which project-scoped features are enabled for the selected project.
+- Pages and worklogs can be deployment-dependent even when a feature flag is present. The CLI now returns explicit compatibility errors for unsupported endpoints.
+
 ## Upgrade
 
 ```bash
-bun update -g @backslash-ux/plane
+bun update -g @backslash-ux/plane-cli
 ```
 
 ## Development
 
 ```bash
-git clone https://github.com/backslash-ux/plane-cli
+git clone https://github.com/backslash-ux/plane-cli-cli
 cd plane-cli
 bun install