feat: add team management commands and enhance work item filtering

Author: Joan-Angelo Enrile

CLAUDE.md

@@ -17,6 +17,7 @@ src/
   api/
     client.ts            # WebApi factory; credential priority: SYSTEM_ACCESSTOKEN > AZURE_DEVOPS_TOKEN > stored
     workItems.ts         # Work item CRUD, comments, branch linking
+    teamSettings.ts      # Team listing and iteration (sprint) resolution
     pullRequests.ts      # PR listing, diff, review, threads
     builds.ts            # Pipeline run list/view/cancel/rerun/download/delete
     search.ts            # Code (Azure Search REST), commits, repos (client-side filter)
@@ -30,6 +31,7 @@ src/
     run/                 # list, view, watch, cancel, rerun, download, delete
     search/              # issues, code, commits, prs, repos, projects
     repo/                # list, clone
+    team/                # list, iteration list
     completion.ts        # Shell completions (bash/zsh/fish/powershell)
   config/index.ts        # Config load: CLI > env > git remote > ~/.ado/config.json
   output/index.ts        # TTY/non-TTY formatting, table, detail, JSON

plugins/azure-devops/skills/azure-devops/SKILL.md

@@ -95,7 +95,7 @@ Available on every command:
 
 | Command | Description |
 |---------|-------------|
-| `ado issue list` | List work items (`-s`, `-a`, `-l`, `-t`, `--limit`) |
+| `ado issue list` | List work items (`-s`, `-a`, `-l`, `-i`, `-t`, `--limit`) |
 | `ado issue view <id>` | Work item details (`--comments`) |
 | `ado issue create` | Create work item (`-t` required, `--type`, `-b`, `-a`, `-l`) |
 | `ado issue edit <id>` | Update fields (`-t`, `-b`, `-s`, `-a`, `-l`) |
@@ -107,9 +107,19 @@ Available on every command:
 
 ### Common patterns
 
+**State filter** accepts boolean expressions: `!Closed & !Resolved`, `Active | In Progress`, `Active,In Progress`. Default (`!removed & !deleted & !closed`) excludes terminal states.
+
+**Iteration filter** (`-i`) defaults to `current` sprint. Use `next`, `all`, or a literal path like `MyProject\Sprint 5`.
+
 ```bash
-# List open bugs assigned to yourself
-ado issue list --state open --type Bug --assignee @me
+# List open bugs assigned to yourself in the current sprint
+ado issue list --type Bug --assignee @me
+
+# List all active items across all sprints
+ado issue list --state Active --iteration all
+
+# List items in the next sprint
+ado issue list --iteration next
 
 # Create a bug
 ado issue create --title "Login fails on Safari" --type Bug --assignee user@org.com
@@ -192,6 +202,27 @@ ado search code "AuthController" --repo backend-api --limit 10
 ado search prs "hotfix"
 ```
 
+## Teams & Iterations
+
+| Command | Description |
+|---------|-------------|
+| `ado team list` | List teams in a project (`--mine`, `--limit`) |
+| `ado team iteration list <team>` | List iterations (sprints) for a team (`--current`) |
+
+```bash
+# List all teams
+ado team list
+
+# List only teams you belong to
+ado team list --mine
+
+# List all iterations for a team
+ado team iteration list "My Team"
+
+# Show just the current sprint
+ado team iteration list "My Team" --current --json
+```
+
 ## Repositories
 
 ```bash

plugins/azure-devops/skills/azure-devops/reference.md

@@ -28,16 +28,19 @@ Generated from source at `src/commands/**/*.ts`. Update this file whenever a com
 
 | Flag | Short | Description | Default |
 |------|-------|-------------|---------|
-| `--state <state>` | `-s` | Filter: `open\|closed\|all` | `open` |
+| `--state <expr>` | `-s` | State filter expression (see below) | `!removed & !deleted & !closed` |
 | `--assignee <who>` | `-a` | Filter by assignee; use `@me` for yourself | — |
 | `--label <tag>` | `-l` | Filter by tag/label | — |
+| `--iteration <path>` | `-i` | Iteration path, or `current`, `next`, `all` | `current` |
 | `--type <type>` | `-t` | Work item type (e.g. `Bug`, `Task`, `User Story`) | — |
 | `--limit <n>` | — | Max items to return | `30` |
 | `--project <project>` | `-p` | Azure DevOps project (overrides config) | — |
 | `--org <url>` | — | Organization URL (overrides config) | — |
 | `--json [fields]` | — | Output as JSON | — |
 | `--web` | `-w` | Open in browser | — |
 
+**State expression syntax:** comma or `|` separates OR clauses; `&` separates AND terms; `!` negates a state. Examples: `Active`, `Active,In Progress`, `!Closed & !Resolved`, `Active | In Progress`.
+
 ## ado issue view \<id\>
 
 | Flag | Short | Description | Default |
@@ -323,6 +326,25 @@ Generated from source at `src/commands/**/*.ts`. Update this file whenever a com
 | `--project <project>` | `-p` | Azure DevOps project | — |
 | `--org <url>` | — | Organization URL | — |
 
+## ado team list
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--mine` | — | Only teams you are a member of | — |
+| `--limit <n>` | — | Max results | `30` |
+| `--project <project>` | `-p` | Azure DevOps project (overrides config) | — |
+| `--org <url>` | — | Organization URL (overrides config) | — |
+| `--json [fields]` | — | Output as JSON | — |
+
+## ado team iteration list \<team\>
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--current` | — | Show only the current iteration | — |
+| `--project <project>` | `-p` | Azure DevOps project (overrides config) | — |
+| `--org <url>` | — | Organization URL (overrides config) | — |
+| `--json [fields]` | — | Output as JSON | — |
+
 ## ado completion \<shell\>
 
 Accepted values for `<shell>`: `bash`, `zsh`, `fish`, `powershell`

src/api/teamSettings.ts

@@ -0,0 +1,47 @@
+import * as azdev from 'azure-devops-node-api';
+import { WebApiTeam } from 'azure-devops-node-api/interfaces/CoreInterfaces';
+import { TeamSettingsIteration } from 'azure-devops-node-api/interfaces/WorkInterfaces';
+
+
+/**
+ * Get a list of teams.
+ */
+export async function getTeams(
+  connection: azdev.WebApi,
+  project: string,
+  options: {
+    /**
+     * If true return all the teams requesting user is member, otherwise return all the teams user has read access.
+     */
+    mine?: boolean;
+    skip?: number;
+    top?: number;
+    /**
+     * A value indicating whether or not to expand Identity information in the result WebApiTeam object.
+     */
+    expandIdentity?: boolean;
+  }
+): Promise<WebApiTeam[]> {
+  const coreApi = await connection.getCoreApi();
+  const teams = await coreApi.getTeams(project, options.mine, options.top, options.skip, options.expandIdentity);
+  return teams;
+}
+
+/**
+ * Get a team's iterations using timeframe filter.
+ */
+export async function getTeamIterations(
+  connection: azdev.WebApi,
+  project: string,
+  team: string,
+  options: {
+    current?: boolean;
+  }
+): Promise<TeamSettingsIteration[]> {
+  const workApi = await connection.getWorkApi();
+
+  const timeframe = options.current ? 'Current' : undefined;
+
+  const iterations = await workApi.getTeamIterations({project, team}, timeframe);
+  return iterations;
+}

src/api/workItems.ts

@@ -107,6 +107,7 @@ export interface WorkItemDetail extends WorkItemSummary {
   priority: string;
   areaPath: string;
   iterationPath: string;
+  acceptanceCriteria: string;
   raw: Record<string, unknown>;
 }
 
@@ -130,20 +131,32 @@ export async function listWorkItems(
     tag?: string;
     limit?: number;
     type?: string;
+    iterationPath?: string;
   }
 ): Promise<WorkItemSummary[]> {
   const witApi = await connection.getWorkItemTrackingApi();
 
   const conditions: string[] = [`[System.TeamProject] = '${project.replace(/'/g, "''")}'`];
 
-  const state = options.state ?? 'open';
-  if (state === 'open') {
-    conditions.push(`[System.State] <> 'Closed'`);
-    conditions.push(`[System.State] <> 'Resolved'`);
-  } else if (state === 'closed') {
-    conditions.push(`([System.State] = 'Closed' OR [System.State] = 'Resolved')`);
+  const orStates = options.state
+    ?.split(/,|\||\|\|/)
+    .map(s => s
+      .split(/&|&&/)
+      .map(t => t.trim())
+      .map(s => ({
+        not: s.startsWith('!'),
+        state: s.replace(/^!/g, "").trim(),
+      })));
+
+  if (orStates && orStates.length > 0) {
+    const statesCondition = orStates
+      .map(andStates => andStates
+        .map(s => `[System.State] ${s.not ? '<>' : '='} '${s.state.replace(/'/g, "''")}'`)
+        .join(' AND ')
+      ).join(' OR ');
+
+    conditions.push(`(${statesCondition})`);
   }
-  // 'all' → no state filter
 
   if (options.assignee) {
     if (options.assignee === '@me') {
@@ -161,6 +174,10 @@ export async function listWorkItems(
     conditions.push(`[System.WorkItemType] = '${options.type.replace(/'/g, "''")}'`);
   }
 
+  if (options.iterationPath) {
+    conditions.push(`[System.IterationPath] CONTAINS '${options.iterationPath.replace(/'/g, "''")}'`);
+  }
+
   const wiql = {
     query: `SELECT [System.Id] FROM WorkItems WHERE ${conditions.join(' AND ')} ORDER BY [System.ChangedDate] DESC`,
   };
@@ -228,6 +245,7 @@ export async function getWorkItem(
       priority: String(f['Microsoft.VSTS.Common.Priority'] ?? ''),
       areaPath: String(f['System.AreaPath'] ?? ''),
       iterationPath: String(f['System.IterationPath'] ?? ''),
+      acceptanceCriteria: String(f['Microsoft.VSTS.Common.AcceptanceCriteria'] ?? ''),
       url: buildOrgUrl(orgUrl, project, wi.id ?? id),
       raw: f as Record<string, unknown>,
     };

src/commands/issue/list.ts

@@ -3,10 +3,65 @@ import { getWebApi } from '../../api/client.js';
 import { listWorkItems } from '../../api/workItems.js';
 import { getConfig } from '../../config/index.js';
 import { outputTable, outputJson, relativeDate, colorState, truncate } from '../../output/index.js';
+import { getTeamIterations, getTeams } from '../../api/teamSettings.js';
+import { WebApi } from 'azure-devops-node-api';
+
+
+async function getIterationPathByOptions(connection: WebApi, project: string, iteration: string | undefined): Promise<string | undefined> {
+  if (!iteration) {
+    return undefined;
+  }
+
+  iteration = iteration.toLowerCase();
+
+  if (iteration === 'all') {
+    return undefined;
+  }
+
+  if (iteration !== 'current' && iteration !== 'next') {
+    return iteration;
+  }
+
+
+  const myTeams = await getTeams(connection, project, { mine: true });
+
+  if (myTeams.length === 0) {
+    process.stdout.write('No teams found for the current user.\n');
+    return undefined;
+  }
+
+  const team = myTeams[0].name!;
+  const iterations = await getTeamIterations(connection, project, team, { current: true });
+
+  if (iterations.length === 0) {
+    process.stdout.write(`No current iteration found for team ${team}.\n`);
+    return undefined;
+  }
+
+  const currentIteration = iterations[0];
+  if (iteration === 'current') {
+    return currentIteration.path;
+  }
+
+  if (iteration === 'next') {
+    const allIterations = await getTeamIterations(connection, project, team, {});
+    const currentIndex = allIterations.findIndex(i => i.id === currentIteration.id);
+
+    if (currentIndex === -1 || currentIndex === allIterations.length - 1) {
+      process.stdout.write(`No next iteration found for team ${team}.\n`);
+      return undefined;
+    }
+
+    return allIterations[currentIndex + 1].path;
+  }
+
+  return undefined;
+}
 
 async function issueListHandler(options: {
   state?: string;
   assignee?: string;
+  iteration?: string;
   label?: string;
   limit?: string;
   project?: string;
@@ -26,12 +81,15 @@ async function issueListHandler(options: {
 
   const connection = await getWebApi(config.orgUrl);
 
+  let iterationPath = await getIterationPathByOptions(connection, config.project, options.iteration);
+
   const items = await listWorkItems(connection, config.project, {
     state: options.state,
     assignee: options.assignee,
     tag: options.label,
     limit: options.limit ? parseInt(options.limit, 10) : 30,
     type: options.type,
+    iterationPath,
   });
 
   if (options.json !== undefined) {
@@ -71,9 +129,10 @@ export function registerIssueList(issueCmd: Command): void {
   issueCmd
     .command('list')
     .description('List work items in a project')
-    .option('-s, --state <state>', 'Filter by state: open|closed|all', 'open')
+    .option('-s, --state <state>', 'Filter by states (comma-separated, e.g. open,closed)', '!removed & !deleted & !closed')
     .option('-a, --assignee <assignee>', 'Filter by assignee (use @me for yourself)')
     .option('-l, --label <label>', 'Filter by tag/label')
+    .option('-i, --iteration <path>', 'Filter by iteration path (or current, next, all)', 'current')
     .option('-t, --type <type>', 'Filter by work item type (e.g. Bug, Task, User Story)')
     .option('--limit <number>', 'Max items to return', '30')
     .option('-p, --project <project>', 'Azure DevOps project (overrides config)')

src/commands/team/index.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import { registerTeamList } from './list.js';
+import { registerTeamIteration } from './iteration.js';
+
+export function registerTeamCommands(program: Command): void {
+  const team = program.command('team').description('Manage Azure DevOps teams');
+  registerTeamList(team);
+  registerTeamIteration(team);
+}