@floh-solutions/pharos-cli 0.1.1 → 0.3.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAO1D,OAAO,EAKL,KAAK,QAAQ,EAEd,MAAM,aAAa,CAAC;AA4FrB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChD,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOhE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAQ1D,OAAO,EAKL,KAAK,QAAQ,EAEd,MAAM,aAAa,CAAC;AA6GrB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChD,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOhE"}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { run as runPlanToBoard } from "@floh-solutions/plan-to-board";
 import { DEFAULT_WRITE_BUDGET, WriteBudget } from "./budget.js";
 import { runComment } from "./commands/comment.js";
+import { runSetup } from "./commands/setup.js";
 import { runTask } from "./commands/task.js";
 import { runWiki } from "./commands/wiki.js";
 import { EXIT_OK, emitText, reportError, usageError, } from "./output.js";
@@ -37,6 +38,23 @@ const USAGE = `pharos — Azure DevOps from a headless shell, for an agent.
 
   pharos <command> [options]
 
+START HERE
+
+  setup                          Everything needed to start, in one command.
+                                 Asks for your organisation, project and token;
+                                 stores the token in your OS keychain rather
+                                 than a file; writes the shell profile that
+                                 SCRIPTED shells read, not just interactive
+                                 ones; installs a Claude skill at user scope so
+                                 every session knows this tool is here; then
+                                 proves it by reading the board and the wiki.
+                                 Those are separate Azure DevOps permissions,
+                                 and a token missing the wiki one works fine
+                                 until the first wiki write days later.
+      --print                    show the shell block and change nothing
+      --stdin                    read the token from a pipe, for scripted setup
+      --no-skill                 do not install the Claude skill
+
 COMMANDS
 
   task <id>                      Everything about one work item in a single call:
@@ -115,12 +133,29 @@ async function dispatch(io, options) {
             "no-wiki-comments": { type: "boolean" },
             "no-related-titles": { type: "boolean" },
         }
-        : CONTENT_OPTIONS;
+        : command === "setup"
+            ? {
+                print: { type: "boolean" },
+                stdin: { type: "boolean" },
+                "no-skill": { type: "boolean" },
+            }
+            : CONTENT_OPTIONS;
     const { values, positionals } = parse(options.argv, { ...GLOBAL_OPTIONS, ...extras });
     if (values["version"] === true)
         return emitText(io, await version(options.cwd));
     if (values["help"] === true || command === undefined)
         return emitText(io, USAGE);
+    // Before the Session: setup is what you run when there is no configuration
+    // yet, so it must not be behind the thing that requires configuration.
+    if (command === "setup") {
+        return runSetup(io, options.env, {
+            org: asString(values["org"]),
+            project: asString(values["project"]),
+            print: values["print"] === true,
+            stdin: values["stdin"] === true,
+            skill: values["no-skill"] !== true,
+        }, options.readStdin ?? readAllStdin, options.client);
+    }
     const session = new Session({
         env: options.env,
         organization: asString(values["org"]),
@@ -151,8 +186,8 @@ async function dispatch(io, options) {
                 text: await content(options, values),
             });
         default:
-            throw usageError(`Unknown command "${command}". Try task, wiki, comment or plan.`, {
-                commands: ["task", "wiki", "comment", "plan"],
+            throw usageError(`Unknown command "${command}". Try setup, task, wiki, comment or plan.`, {
+                commands: ["setup", "task", "wiki", "comment", "plan"],
             });
     }
 }

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/setup.d.ts

@@ -0,0 +1,16 @@
+import { AdoClient } from "@floh-solutions/ado-core";
+import { type ExitCode, type Io } from "../output.js";
+export interface SetupOptions {
+    org?: string | undefined;
+    project?: string | undefined;
+    /** Print the shell block and change nothing. For people who manage dotfiles themselves. */
+    print: boolean;
+    /** Read the token from stdin instead of prompting — for scripted setup. */
+    stdin: boolean;
+    /** Install the Claude skill. Default true; `--no-skill` opts out. */
+    skill: boolean;
+}
+export declare function runSetup(io: Io, env: NodeJS.ProcessEnv, options: SetupOptions, readStdin: () => Promise<string>, 
+/** Injected so the verification can be driven against a mock transport. */
+verifyWith?: AdoClient): Promise<ExitCode>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/commands/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,SAAS,EAAW,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AA4ClF,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,2FAA2F;IAC3F,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,EAAE,EACN,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC;AAChC,2EAA2E;AAC3E,UAAU,CAAC,EAAE,SAAS,GACrB,OAAO,CAAC,QAAQ,CAAC,CAqDnB"}

package/dist/commands/setup.js

@@ -0,0 +1,337 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+/**
+ * `pharos setup` — get somebody from "installed" to "working" in one command.
+ *
+ * ## Why this exists at all, when the tool reads three environment variables
+ *
+ * Because "set three environment variables" is where people actually fail, and
+ * they fail *silently and late*. The three ways it goes wrong, all seen:
+ *
+ *   1. **The token ends up in a file.** Told to `export ADO_PAT=…`, the obvious
+ *      move is to paste it into a dotfile, where it lives in plaintext,
+ *      backs itself up, and gets committed by somebody eventually.
+ *   2. **The wrong dotfile.** zsh reads `.zshrc` only for INTERACTIVE shells,
+ *      so the variables work when you type in Terminal and are invisible to
+ *      anything scripted — a hook, CI, an agent shelling out. The failure is a
+ *      config error that reads as a broken tool.
+ *   3. **A scope is missing.** Work Items and Wiki are separate Azure DevOps
+ *      permissions. A token with only the first works perfectly until the first
+ *      wiki write, days later, and then fails with a 401 that looks like a bad
+ *      token rather than a narrow one.
+ *
+ * This does all three correctly, then **proves it** by making real calls.
+ *
+ * ## The boundary this does NOT cross
+ *
+ * The tool's RUNTIME still reads `ADO_PAT` from the environment and nothing
+ * else — no keychain, no config file, no credential helper. That is what keeps
+ * the same binary working in CI and under an unattended agent, and it is not
+ * negotiable.
+ *
+ * This command is a **bootstrapper**, not a credential path: run once,
+ * explicitly, interactively. It puts the token in the OS keychain and writes a
+ * shell snippet that reads it back out. So the *shell* resolves the secret and
+ * the *tool* still just inherits an environment variable — which is why running
+ * `pharos` under CI with `ADO_PAT` set works identically and never calls any of
+ * this.
+ */
+const BEGIN = "# >>> pharos cli >>>";
+const END = "# <<< pharos cli <<<";
+/** Keychain service name. Deliberately not the Pharos app's — separate tools, separate secrets. */
+const KEYCHAIN_SERVICE = "pharos-cli-ado-pat";
+export async function runSetup(io, env, options, readStdin, 
+/** Injected so the verification can be driven against a mock transport. */
+verifyWith) {
+    const interactive = process.stdin.isTTY === true && !options.stdin;
+    const org = options.org ?? env["ADO_ORG"] ?? (interactive ? await ask(ORG_PROMPT) : "");
+    if (org === "")
+        throw usageError("No organisation. Pass --org, or run this in a terminal.");
+    const project = options.project ?? env["ADO_PROJECT"] ?? (interactive ? await ask(PROJECT_PROMPT) : "");
+    if (project === "")
+        throw usageError("No project. Pass --project, or run this in a terminal.");
+    const target = profileTarget(env);
+    if (options.print) {
+        return emitText(io, shellBlock(org, project, target.secret));
+    }
+    const token = options.stdin
+        ? (await readStdin()).trim()
+        : interactive
+            ? await askSecret(TOKEN_PROMPT)
+            : "";
+    if (token === "") {
+        throw usageError("No token. Run this in a terminal to be prompted, or pipe it in with --stdin.");
+    }
+    // Store the secret BEFORE touching the profile: a profile that references a
+    // secret which is not there yet is worse than no profile change at all.
+    await storeSecret(token, target.secret);
+    const wrote = await updateProfile(target.profile, shellBlock(org, project, target.secret));
+    const skill = options.skill ? await installSkill(env) : "skipped";
+    // Prove it, rather than declaring success and letting them find out later.
+    const checks = await verify(org, project, token, verifyWith);
+    return emit(io, {
+        applied: true,
+        organization: org,
+        project,
+        tokenStoredIn: describeSecret(target.secret),
+        profile: target.profile,
+        profileAction: wrote,
+        skill,
+        checks,
+        // The variables are exported by a file that this shell already read, so
+        // they are not in it. Saying so beats somebody concluding it failed.
+        hint: checks.workItems.ok && checks.wiki.ok
+            ? `Open a new terminal, then run: pharos task <id>`
+            : "Setup wrote everything, but a scope check failed — see `checks`. Fix the token's "
+                + "scopes in Azure DevOps and run `pharos setup` again.",
+    });
+}
+/**
+ * Which file to write, and where the token lives.
+ *
+ * **zsh gets `.zshenv`, not `.zshrc`, and that is the single most important
+ * decision here.** `.zshrc` is read only by interactive shells, so a setup that
+ * lands there works in Terminal and is invisible to every scripted or agent-run
+ * invocation — which is the exact case this tool exists to serve.
+ *
+ * bash has no true equivalent. `.bashrc` is skipped by non-interactive shells
+ * too, but it is the least-bad option and the summary says so rather than
+ * implying a guarantee that is not there.
+ */
+function profileTarget(env) {
+    const shell = env["SHELL"] ?? "";
+    // `HOME` rather than `homedir()`: on every platform we support they agree,
+    // and reading the variable is what lets this be exercised against a scratch
+    // directory instead of somebody's actual dotfiles.
+    const home = env["HOME"] ?? homedir();
+    // `PHAROS_TOKEN_FILE` puts the token in a mode-600 file instead of the OS
+    // keychain. Not a test hook — a container, a CI image and a headless Linux
+    // box all have no keychain to speak of, and forcing one on macOS is a
+    // reasonable preference to hold.
+    const override = env["PHAROS_TOKEN_FILE"];
+    const secret = override !== undefined && override !== ""
+        ? { kind: "file", path: override }
+        : platform() === "darwin"
+            ? { kind: "keychain" }
+            : { kind: "file", path: join(home, ".config", "pharos", "token") };
+    if (shell.endsWith("zsh"))
+        return { profile: join(home, ".zshenv"), secret };
+    if (shell.endsWith("bash")) {
+        return {
+            profile: join(home, platform() === "darwin" ? ".bash_profile" : ".bashrc"),
+            secret,
+        };
+    }
+    // Unknown shell: still write something sensible, and `--print` exists for
+    // anyone who would rather paste it themselves.
+    return { profile: join(home, ".profile"), secret };
+}
+function shellBlock(org, project, secret) {
+    const read = secret.kind === "keychain"
+        ? `"$(security find-generic-password -s ${KEYCHAIN_SERVICE} -w 2>/dev/null)"`
+        : `"$(cat ${secret.path} 2>/dev/null)"`;
+    return [
+        BEGIN,
+        "# Written by `pharos setup`. Safe to edit; re-running setup replaces this block.",
+        "#",
+        "# The token is NOT stored here — it is read out of "
+            + (secret.kind === "keychain" ? "your login keychain." : `${secret.path} (mode 600).`),
+        "# pharos itself only ever reads these environment variables, which is what",
+        "# lets the same command work in CI and under an unattended agent.",
+        `export ADO_ORG=${shellQuote(org)}`,
+        `export ADO_PROJECT=${shellQuote(project)}`,
+        `export ADO_PAT=${read}`,
+        END,
+    ].join("\n");
+}
+// MARK: - The skill
+/**
+ * Install the Claude skill to **user scope**.
+ *
+ * ## Why this ships with the tool instead of living in the repo
+ *
+ * Because the knowledge has to be somewhere the reader can actually reach, and
+ * a repo is not that place for anybody but its owner. Documentation in
+ * `AGENTS.md` or a `docs/` folder is invisible to a teammate working in their
+ * own checkout, and a setup guide is read once at install time and never again.
+ * Neither survives into the session three weeks later where the decision
+ * actually gets made.
+ *
+ * A user-scope skill does: it loads in every session, in any directory, on that
+ * person's machine. So it travels with the npm package and gets installed by
+ * the same command that configures the token — one step, not a thing to
+ * remember.
+ *
+ * **What is in it is deliberately NOT the API traps.** Those are handled inside
+ * this package and a caller cannot reach them; a second copy in prose would
+ * only be a copy that can drift. What it carries is the part no code can: which
+ * tool to reach for, what the exit codes oblige you to do, and the handful of
+ * Azure DevOps facts that are architectural rather than fixable — a wiki is a
+ * git repository, there is no wiki event, ancestors are not created for you.
+ *
+ * Overwritten on every run so an upgrade refreshes it. Failure is reported and
+ * never fatal: not having the skill is a worse experience, not a broken setup.
+ */
+async function installSkill(env) {
+    const home = env["HOME"] ?? homedir();
+    const destination = join(home, ".claude", "skills", "pharos", "SKILL.md");
+    try {
+        // Resolved relative to the compiled file, so it works from dist/ in a
+        // global npm install as well as from src/ in this checkout.
+        const source = new URL("../../skill/SKILL.md", import.meta.url);
+        const body = await readFile(source, "utf8");
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, body, "utf8");
+        return destination;
+    }
+    catch (error) {
+        return `not installed (${messageOf(error)})`;
+    }
+}
+// MARK: - Doing it
+async function storeSecret(token, secret) {
+    if (secret.kind === "keychain") {
+        // `-U` updates an existing entry rather than failing, so re-running after a
+        // token rotation is the same command.
+        await run("security", [
+            "add-generic-password",
+            "-U",
+            "-a",
+            process.env["USER"] ?? "pharos",
+            "-s",
+            KEYCHAIN_SERVICE,
+            "-w",
+            token,
+        ]);
+        return;
+    }
+    const path = secret.path;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${token}\n`, { mode: 0o600 });
+    // Explicit, because an existing file keeps its old mode through writeFile.
+    await chmod(path, 0o600);
+}
+/** Replace the block if it is there, append it if it is not. Never duplicate. */
+async function updateProfile(path, block) {
+    let existing = "";
+    try {
+        existing = await readFile(path, "utf8");
+    }
+    catch {
+        await writeFile(path, `${block}\n`, { mode: 0o600 });
+        return "created";
+    }
+    const start = existing.indexOf(BEGIN);
+    const end = existing.indexOf(END);
+    if (start !== -1 && end > start) {
+        const updated = existing.slice(0, start) + block + existing.slice(end + END.length);
+        await writeFile(path, updated, "utf8");
+        return "replaced";
+    }
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    await writeFile(path, `${existing}${separator}${block}\n`, "utf8");
+    return "appended";
+}
+/**
+ * Check the two scopes SEPARATELY, because Azure DevOps grants them separately.
+ *
+ * A token with Work Items but not Wiki behaves perfectly until the first wiki
+ * write — possibly days later — and then fails with a 401 that looks like a bad
+ * token rather than a narrow one. Finding that out now costs one request.
+ */
+async function verify(org, project, pat, injected) {
+    const client = injected ?? new AdoClient({ organization: org, project, pat });
+    const workItems = await client.wiql
+        .query("SELECT [System.Id] FROM WorkItems", { top: 1 })
+        .then(() => ({ ok: true, detail: "work item read works" }))
+        .catch((error) => ({
+        ok: false,
+        detail: `work items unreadable — check the org, the project, and the token's `
+            + `"Work Items (Read, write, & manage)" scope. ${messageOf(error)}`,
+    }));
+    const wiki = await new WikiApi(client.http)
+        .listWikis()
+        .then((wikis) => ({ ok: true, detail: `wiki read works (${wikis.length} found)` }))
+        .catch((error) => ({
+        ok: false,
+        detail: `wiki unreadable — this is a SEPARATE permission from work items; check the `
+            + `token's "Wiki (Read & write)" scope. ${messageOf(error)}`,
+    }));
+    return { workItems, wiki };
+}
+// MARK: - Prompts
+const ORG_PROMPT = "Azure DevOps organisation\n"
+    + "  (from your board's URL: https://dev.azure.com/THIS/project)\n> ";
+const PROJECT_PROMPT = "Project\n  (the next part of that URL: https://dev.azure.com/org/THIS)\n> ";
+const TOKEN_PROMPT = "Personal access token\n"
+    + "  User settings → Personal access tokens → New Token.\n"
+    + "  Scopes, both of them: Work Items (Read, write, & manage) AND Wiki (Read & write).\n"
+    + "  It will not be echoed, and it is stored in your keychain rather than a file.\n> ";
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await new Promise((resolve) => rl.question(question, resolve))).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Prompt without echoing.
+ *
+ * Readline is given a sink for its output rather than stdout, so the keystrokes
+ * it would normally echo go nowhere; the prompt is written directly instead.
+ * That avoids overriding readline's private `_writeToOutput`, which is the
+ * usual trick for this and breaks whenever Node tidies its internals.
+ */
+async function askSecret(question) {
+    process.stdout.write(question);
+    const sink = new Writable({
+        write(_chunk, _encoding, done) {
+            done();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output: sink, terminal: true });
+    try {
+        const answer = await new Promise((resolve) => rl.question("", resolve));
+        process.stdout.write("\n");
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+// MARK: - Small helpers
+function run(command, args) {
+    return new Promise((resolve, reject) => {
+        // No shell, and the token is an argv entry rather than part of a command
+        // string — nothing to quote, nothing to interpolate, and it never reaches a
+        // shell history.
+        const child = spawn(command, args, { stdio: "ignore" });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} exited ${String(code)}`));
+        });
+    });
+}
+function describeSecret(secret) {
+    return secret.kind === "keychain"
+        ? `login keychain (service "${KEYCHAIN_SERVICE}")`
+        : `${secret.path} (mode 600)`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Azure DevOps from a headless shell, for an agent: the whole context of a task in one call, and the wiki/comment verbs Microsoft's MCP server does not ship.",
   "license": "UNLICENSED",
   "author": "FLOH Solutions",
@@ -17,14 +17,15 @@
     "pharos": "./dist/bin.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skill"
   ],
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
-    "@floh-solutions/plan-to-board": "0.1.1",
-    "@floh-solutions/ado-core": "0.1.0"
+    "@floh-solutions/ado-core": "0.1.0",
+    "@floh-solutions/plan-to-board": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skill/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: pharos
+description: "Use whenever Azure DevOps work is involved — reading or updating a work item, task, bug, story or epic; anything with a board, backlog, sprint or iteration; reading or writing a project wiki page; commenting on a task or a wiki page; linking a plan to an epic; or when the user names a work item by number (\"pick up 4821\", \"what's on 210\"). Also use when deciding between the Azure DevOps MCP server and the `pharos` CLI, or when an Azure DevOps call fails and you need to know whether to retry it."
+license: Proprietary
+---
+
+# Working Azure DevOps with `pharos`
+
+`pharos` is a CLI that gives you the full Azure DevOps surface from a shell,
+authenticated by an environment variable rather than a browser login. Run
+`pharos --help` for the complete verb list; this skill is the part that is not
+in the help text.
+
+## Start every task with one command
+
+```bash
+pharos task <id>
+```
+
+That returns the work item, its comments, its attachments, its relations **with
+their titles**, and the full content of every linked wiki page **plus the
+discussion on those pages** — in one call.
+
+**Do this before anything else, and do not assemble it yourself.** By hand it is
+five or six lookups across two tools, and the plan a colleague wrote is usually
+on a linked wiki page rather than in the description. A task worked without it
+is a task worked without the plan.
+
+Add `--pretty` when a person will read the output.
+
+Anything that could not be fetched appears in `problems[]`. **If that array is
+not empty, say so before acting** — a context with an invisible hole in it gets
+reasoned from confidently.
+
+## Which tool: `pharos` or the Azure DevOps MCP server
+
+If both are available, they overlap. The dividing line:
+
+| | |
+|---|---|
+| **Use `pharos`** | anything touching a **wiki page's comments** (the MCP has no tool for these at all), deleting a comment, reactions, deleting a wiki page, and `pharos task <id>` for gathering context |
+| **Either works** | reading and querying work items, creating them, updating fields and state, adding a comment, reading a wiki page |
+| **The MCP may be better** | code search, repository and pull request work, anything outside work items and wikis |
+
+When in doubt use `pharos`: its failure modes are structured and its guards are
+explicit.
+
+## Reading the outcome
+
+Output is a contract. **Success is JSON on stdout; failure is JSON on stderr
+with a non-zero exit.** An empty array with exit 0 is a query that matched
+nothing — a different fact from a failure.
+
+| exit | meaning | what to do |
+|---|---|---|
+| `0` | it worked | carry on |
+| `1` | the call failed | check `kind`; retry only if it is `rateLimit` (wait `retryAfterMs`) or transient |
+| `2` | called wrong, or not configured | **never retry unchanged.** Fix the call, or the setup |
+| `3` | a guard here refused | re-run with `--yes`, or raise `--max-writes` — after deciding it is right |
+
+`"kind": "conflict"` means somebody wrote first. Your work is still valid:
+re-read, re-apply. It carries both revisions — and note that **posting a comment
+bumps `System.Rev`**, so a revision mismatch is not proof anybody edited the
+same field.
+
+## Destructive verbs refuse by default. Read the refusal.
+
+```bash
+pharos wiki delete /Plans/Old              # exit 3, nothing changed
+pharos wiki delete /Plans/Old --yes        # done
+```
+
+**Exit 3 with `"kind": "refused"` means nothing happened.** Do not report the
+work as done. The refusal carries a preview of what it would have done — check
+that preview is what you intended before adding `--yes`, rather than reflexively
+re-running with the flag.
+
+Replacing a wiki page needs `--yes`; creating one does not. The refusal tells
+you how many bytes are at stake, which is how you notice you are about to
+overwrite somebody's page instead of writing a new one.
+
+`--dry-run` gives the preview with exit 0 when you want to look without being
+refused.
+
+## The traps are handled. Do not work around them.
+
+Every known Azure DevOps failure of this kind is handled inside the tool: the
+lost-update on wiki writes, the deleted-comment field that lies, the reaction
+call that needs an empty body, artifact links that must carry a project GUID,
+relation removal that would otherwise take the wrong link.
+
+**So if something looks like it needs a workaround, it does not.** A `pharos`
+command failing means the request was genuinely wrong or the API genuinely
+refused — read the error rather than reaching for `curl`. If you find a real gap,
+say so plainly; do not paper over it with raw REST calls that skip the guards.
+
+## Three things no tool can fix
+
+1. **A wiki is a git repository.** Two writes to the same wiki at the same
+   moment are two pushes racing for one HEAD. Write pages one at a time.
+2. **There is no wiki event in service hooks.** You cannot subscribe to "a wiki
+   page changed" — only to `git.push` on the wiki's repository. If you need to
+   react to wiki edits, that is the only route.
+3. **Wiki ancestors are not created for you.** Writing `/A/B` when `/A` does not
+   exist is refused. Build a page tree top-down, one write per level.
+
+## The loop
+
+Working a task end to end, in the order that keeps the board honest:
+
+1. `pharos task <id>` — read everything, including the linked plan.
+2. If a plan is needed, write it: `pharos wiki write /Plans/<name> --stdin`,
+   then link it to the epic so the next person finds it the same way you did.
+3. Break it down — create the child items.
+4. `pharos comment add <id> --file notes.md` — decisions belong on the item,
+   not only in a chat log that nobody else can read.
+5. Move the state when the work moves, not at the end.
+
+**Every person uses their own token.** Board attribution is per-person, so
+anything you do is recorded against whoever owns `ADO_PAT`. Never suggest
+sharing one.
+
+## When it is not set up
+
+`"kind": "config"` on exit 2 means the environment is missing. Run:
+
+```bash
+pharos setup
+```
+
+It asks for the organisation, project and token, stores the token in the OS
+keychain rather than a file, writes the right shell profile, and verifies both
+permission scopes — Work Items and Wiki are separate in Azure DevOps, and a
+token missing the second one works until the first wiki write.
+
+Variables live in the environment (`ADO_ORG`, `ADO_PROJECT`, `ADO_PAT`) and
+**never in the tool's own config**, which is what lets the same command run in
+CI and unattended. After setup, a **new** shell is needed.