@oozou/velocity 0.1.3 → 0.1.4

package/AGENT.md

@@ -0,0 +1,210 @@
+# Velocity CLI — Agent Reference
+
+You are operating the `velocity` CLI. This file is the contract — every
+flag, output shape, and failure mode you need is here. If a behavior
+isn't documented below, run `velocity <subcommand> --help` first; don't
+guess.
+
+## Output contract
+
+- Mode is **autodetected from TTY**: a non-TTY stdout (i.e. anything
+  an agent captures — pipes, subprocess stdout, redirects) gets JSON
+  by default. You usually don't need `--json` explicitly.
+- **Pass `--json` anyway** if you want to be defensive against agent
+  runtimes that allocate a pty for the subprocess. Cheap insurance.
+- Under JSON mode stdout is exactly one JSON value per command, schema
+  stable. Errors print `{"error":"<message>"}` on stderr and exit
+  non-zero. Always check the exit code.
+- Don't parse the human view — it's tables and prose, not stable.
+
+## Authentication
+
+The CLI must be authenticated before any non-`auth` command. Three ways:
+
+1. `velocity auth login` — opens a browser. Interactive only.
+2. `VELOCITY_TOKEN=<vel_…>` env var — for headless/CI/agent-runner
+   environments. Token is a regular Velocity API token (Settings →
+   API Tokens in the web app).
+3. A previously written credentials file from a prior `auth login`
+   (lives at `~/.config/velocity/credentials.json`, mode `0600`).
+
+To check: `velocity auth status` returns
+`{"authenticated": true|false, ...}`. If `false`, ask the user to run
+`velocity auth login` — never try to prompt for credentials yourself.
+
+`velocity whoami` is the lighter probe: `{authenticated, user}`.
+
+## Project context
+
+Most commands operate on a single project. Resolution order:
+
+1. `--project <slug-or-id>` flag on the command.
+2. `VELOCITY_PROJECT` env var.
+3. The persisted active project (set by `velocity projects use <slug>`).
+
+Projects accept either a slug (`acme-website`) or a Convex `_id`. Slugs
+are returned by `velocity projects list` and are the preferred form.
+
+If no project is resolvable the command exits non-zero with
+`{"error":"No project selected..."}`. List options with
+`velocity projects list` and either pass `--project <slug>` or set
+the active project once with `velocity projects use <slug>`.
+
+## Commands
+
+All commands send/receive JSON. Examples below assume an authenticated
+session and an active project where relevant.
+
+### Discovery
+
+```
+velocity whoami                                          # → { authenticated, user }
+velocity projects list                                   # → [{_id, slug, name, isActive, client}]
+velocity projects get <slug-or-id>                       # → full project record
+velocity projects current                                # → {env, projectId}
+velocity members                                         # → [{_id, name, email, role}]
+velocity stats                                           # → {totals, statusBreakdown, ...}
+velocity activity --limit 20                             # → [{type, actor, target, at}]
+```
+
+### Stories
+
+Stories are identified by their globally-unique `number` (an integer like
+`10634`). Use that, not the Convex `_id`.
+
+```
+velocity stories list                                    # → [{_id, number, title, status, priority, type}]
+velocity stories get <number>                            # → full story (includes assignee, sprint, parent, children)
+velocity stories create \
+  --title "Title" \
+  --type feature|bug|chore \
+  --status <stage> \
+  --priority urgent|high|medium|low \
+  [--description "..." | --description-file <path> | --description-stdin] \
+  [--assignee <userId>] [--sprint <sprintId>] [--release <releaseId>] \
+  [--parent <storyId>] [--points <num>] \
+  [--complexity none|low|medium|high]
+# → { _id, number, projectId, ... }
+
+velocity stories update <number> [same flags as create, all optional;
+                                  pass "null" to clear a relation]
+velocity stories delete <number>                         # → { status: "ok" }
+```
+
+Valid `--status` values come from the project's configured stages
+(typically `backlog`, `in_progress`, `done`, etc.). On invalid status
+the server returns 400 — read the `error` field for the allowed list.
+
+### Sprints
+
+```
+velocity sprints list                                    # → [{_id, name, startDate, endDate, status}]
+velocity sprints active                                  # → {sprint, stories, totalPoints, donePoints}
+velocity sprints get <sprintId>                          # → full sprint record + stories
+velocity sprints stories <sprintId>                      # → [stories assigned to this sprint]
+```
+
+### Releases
+
+```
+velocity releases list [--include-archived]              # → [{_id, name, version, status, targetDate}]
+velocity releases get <releaseId>                        # → full release + grouped changelog
+velocity releases create \
+  --name "v1.2 Launch" \
+  --target-date 2026-06-30 \
+  [--version 1.2.0] \
+  [--description "..." | --description-file <path> | --description-stdin]
+# → { _id, ... }
+
+velocity releases update <releaseId> [same flags, all optional]
+velocity releases status <releaseId> planned|in_progress|released|archived
+velocity releases assign <storyNumber> <releaseId>
+velocity releases unassign <storyNumber>
+```
+
+Setting status to `released` or `archived` locks the release — further
+edits are rejected.
+
+### Comments
+
+Comments attach to a story (by story number).
+
+```
+velocity comments list <storyNumber>                     # → [{_id, body, user, _creationTime}]
+velocity comments add <storyNumber> "body"
+velocity comments add <storyNumber> --file ./comment.md
+velocity comments add <storyNumber> --stdin < comment.md
+```
+
+### Notes
+
+```
+velocity notes list                                      # → [{_id, title, updatedAt}]
+velocity notes get <noteId>                              # → full note + content (markdown)
+velocity notes create \
+  --title "Title" \
+  [--content "..." | --file <path> | --stdin]
+velocity notes update <noteId> [--title "..."] \
+  [--content "..." | --file <path> | --stdin]
+velocity notes delete <noteId>                           # → { status: "ok" }
+```
+
+### Todos
+
+```
+velocity todos list                                      # → [{_id, title, priority, dueDate, done}]
+velocity todos create \
+  --title "Title" \
+  [--priority urgent|high|medium|low] \
+  [--due-date 2026-06-15] [--assignee <userId>]
+velocity todos update <todoId> [--title "..."] \
+  [--priority ...] [--due-date <yyyy-mm-dd> | --due-date null] \
+  [--assignee <userId> | --assignee null] \
+  [--done]
+velocity todos delete <todoId>                           # → { status: "ok" }
+```
+
+## Failure modes
+
+| Exit code / error fragment | Meaning | What to do |
+| --- | --- | --- |
+| stdout has JSON, exit 0 | Success | Continue. |
+| `"Not authenticated"` | Token missing or revoked | Ask user to run `velocity auth login`. |
+| `"No project selected"` | No active project resolvable | Tell user to run `velocity projects use <slug>` or pass `--project <slug>`. |
+| `"Project not found"` | Bad slug or id | List options via `velocity projects list`. |
+| `"Story not found"` / `"Note not found"` etc. | Bad numeric id / id | Confirm the value via the relevant `list` command. |
+| `"Cannot assign story to a locked release"` | Release is `released`/`archived` | Either pick an unlocked release or unlock it (web UI only). |
+| Any 500 / unexpected error | Server-side issue | Retry once; if persistent, surface to user verbatim. |
+
+Always check the exit code before parsing stdout.
+
+## Conventions
+
+- Pass long-text inputs (descriptions, note bodies, comment bodies) via
+  `--file <path>` or `--stdin` when the content is more than a line —
+  it avoids quoting headaches and surfaces shell injection less often.
+- For mutations, prefer named flags over positional arguments. The
+  flag names match the field names in the JSON response, so reading
+  back what you just wrote is straightforward.
+- To clear an optional relation (assignee, sprint, release, parent,
+  due-date), pass `null` as the value: `--assignee null`.
+- Web URLs for stories, notes, and releases are not returned by these
+  commands; they're constructed as
+  `https://velocity.oozou.com/projects/<projectId>/stories/<number>`
+  etc. when you need to link from agent output to the web app.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `VELOCITY_TOKEN` | Bearer token; bypasses the credentials file. |
+| `VELOCITY_API_BASE` | Override the API base URL. |
+| `VELOCITY_PROJECT` | Override the active project slug or id. |
+| `VELOCITY_OUTPUT` | `json` or `human`; forces output mode. |
+| `VELOCITY_NO_UPDATE_NOTIFIER` | Set to `1` to silence the update prompt. |
+
+## When in doubt
+
+Run `velocity <cmd> --help` for the live flag list — it always matches
+the binary you're invoking, even if this file drifts. Then come back
+to this contract for shape and failure-mode details.

package/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: velocity
+description: Operate the Velocity CLI to read and manage projects, stories, sprints, releases, notes, todos, and comments. Use whenever the user asks to look at Velocity data or to create/update/delete anything in their Velocity workspace.
+---
+
+# velocity
+
+You have access to the `velocity` CLI. It is the sanctioned way to read
+or write Velocity content from a terminal or agent runtime.
+
+**Always read [AGENT.md](./AGENT.md) before issuing your first command in
+a session.** It contains the full command surface, the JSON output
+contract, project resolution rules, and the failure modes you will
+hit. Do not guess command names or flag shapes.
+
+If `AGENT.md` is not on disk (sandboxed environments), run
+`velocity agent-help` to print the same content to stdout.

package/dist/index.js

@@ -1316,90 +1316,33 @@ var registerUpdateCommand = (program2) => {
 };
 
 // src/commands/agent-help.ts
-var HELP_TEXT = `# Velocity CLI agent guide
-
-The Velocity CLI is a REST client over /api/v1/* with two output modes:
-- Human (default on a TTY): tabular plain text.
-- JSON (default when stdout is piped, or pass --json): a single JSON value per command.
-
-## Auth
-- \`velocity auth login\` \u2014 opens a browser, polls for approval. Stores creds at
-  ~/.config/velocity/credentials.json (mode 0600).
-- \`velocity auth logout\` \u2014 deletes the local credentials file.
-- \`velocity auth status\` \u2014 show session details. \`velocity whoami\` \u2014 short form.
-- Headless escape hatch: set \`VELOCITY_TOKEN=vel_\u2026\`. \`VELOCITY_API_BASE\`
-  overrides the URL.
-
-## Active project
-Most commands need a projectId. Resolution:
-1. \`--project <id>\` flag
-2. \`VELOCITY_PROJECT\` env var
-3. The active-project file (\`velocity projects use <slug>\`)
-
-## Command tree
-
-\`\`\`
-auth login | logout | status
-whoami
-
-projects list
-projects get [slug-or-id]
-projects use <slug-or-id> | current | reset
-
-update                 # upgrade the CLI to the latest version on npm
-
-stories list
-stories get <number>
-stories create --title --type --status --priority [--description --assignee --sprint --release --parent --points --complexity]
-stories update <number> [--title --description --type --status --priority --assignee --sprint --release --parent --points --complexity]
-stories delete <number>
-
-sprints list
-sprints active
-sprints get <sprintId>
-sprints stories <sprintId>
-
-releases list [--include-archived]
-releases get <releaseId>
-releases create --name --target-date [--version --description]
-releases update <releaseId> [--name --target-date --version --description]
-releases status <releaseId> <planned|in_progress|released|archived>
-releases assign <storyNumber> <releaseId>
-releases unassign <storyNumber>
-
-comments list <storyNumber>
-comments add <storyNumber> <body> | --body | --file | --stdin
-
-notes list
-notes get <noteId>
-notes create --title [--content | --file | --stdin]
-notes update <noteId> [--title --content | --file | --stdin]
-notes delete <noteId>
-
-todos list
-todos create --title [--priority --due-date --assignee]
-todos update <todoId> [--title --priority --due-date --assignee --done]
-todos delete <todoId>
-
-stats
-activity [--limit N]
-members
-\`\`\`
-
-## Output rules for scripts
-- Stdout: success result (human or JSON depending on TTY / flags / VELOCITY_OUTPUT).
-- Stderr: prompts, errors, browser hints. Never JSON success data.
-- Exit code: 0 on success, non-zero on failure.
-- 401 from any command \u2192 token rotted or revoked. Re-run \`velocity auth login\`.
-
-## Errors
-JSON mode errors come back as \`{"error":"..."}\` on stderr with a non-zero exit
-code. Human mode prints \`Error: ...\` on stderr.
-`;
+import { readFile as readFile4 } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname as dirname3, join as join2 } from "path";
+var findAgentDoc = async () => {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "..", "AGENT.md"),
+    // dist/index.js → ../AGENT.md
+    join2(here, "..", "..", "AGENT.md")
+    // dev: src/commands → ../../AGENT.md
+  ];
+  for (const path of candidates) {
+    try {
+      return await readFile4(path, "utf8");
+    } catch {
+    }
+  }
+  throw new Error(
+    "AGENT.md not found. Reinstall the CLI with `npm i -g @oozou/velocity@latest`."
+  );
+};
 var registerAgentHelpCommand = (program2) => {
-  program2.command("agent-help").description("Print a markdown guide for AI agents using the CLI").action(async function() {
+  program2.command("agent-help").description("Print the agent contract (AGENT.md) to stdout").action(async function() {
     try {
-      writeResult(this, { markdown: HELP_TEXT }, () => HELP_TEXT);
+      const doc = await findAgentDoc();
+      process.stdout.write(doc);
+      if (!doc.endsWith("\n")) process.stdout.write("\n");
     } catch (err) {
       exitWithError(err, this);
     }
@@ -1407,7 +1350,7 @@ var registerAgentHelpCommand = (program2) => {
 };
 
 // src/index.ts
-var VERSION = "0.1.3";
+var VERSION = "0.1.4";
 if (process.stdout.isTTY && process.env.VELOCITY_NO_UPDATE_NOTIFIER !== "1") {
   try {
     updateNotifier({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oozou/velocity",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Velocity CLI — browser-based auth + REST client for the Velocity project management API.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://velocity.oozou.com",
@@ -25,6 +25,8 @@
   },
   "files": [
     "dist",
+    "AGENT.md",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],