# 12. Glossary

## A

**agdt**
: Abbreviation for "agentic-devtools"; used as prefix for all CLI commands

**AI Assistant**
: GitHub Copilot or similar AI-powered coding assistant that executes commands on behalf of the developer

**Auto-approval**
: VS Code feature that remembers command approvals; the goal is to minimize required approvals

**Auto-session**
: Behavior where an `agdt-initiate-*-workflow` command automatically launches a Copilot
CLI session after workflow initiation (and auto-setup when needed). The session starts
with a short static workflow-specific **bootstrap prompt** (not the full rendered prompt).
For most workflows it instructs Copilot to run `agdt-get-next-workflow-prompt`, which then
loads the rendered workflow prompt. The PR review workflow is an exception: its bootstrap
prompt instructs `agdt-advance-workflow pull-request-overview` instead. When a new
worktree is opened in VS Code, a `folderOpen` auto-start task always starts an interactive
Copilot session regardless of `--interactive`. For direct CLI invocations, `--interactive`
controls whether the session attaches to a terminal (`true`, requires TTY + VS Code) or
runs as a detached background process (`false`, default; not an agdt background task —
use `copilot.*` state keys to locate the session log file). Falls back to printing the
rendered prompt to the console when a session cannot be started.

**Azure DevOps (ADO)**
: Microsoft's DevOps platform providing Git repositories, pull requests, work items, and CI/CD pipelines

## B

**Background Task**
: Long-running operation spawned as subprocess that runs independently and doesn't block the main process

**Building Block**
: A component, module, or service that forms part of the system architecture

## C

**Checklist**
: Implementation checklist generated by workflow; tracks progress of work items

**CLI**
: Command-Line Interface; the primary interface for agentic-devtools

**Copilot Chat**
: GitHub Copilot's chat interface in VS Code; can execute commands via agents

**Cross-cutting Concept**
: Architectural aspect that affects multiple modules (e.g., error handling, logging)

## D

**Dispatcher**
: Core module that routes commands and handles repo-local virtual environment detection

**Dry Run**
: Mode where commands show what they would do without actually executing

## E

**Epic**
: Large Jira work item that contains multiple issues

**Entry Point**
: Python script registered in `pyproject.toml` that becomes a CLI command

**Event-driven**
: Architecture pattern where state changes trigger workflow transitions

## F

**File Lock**
: Mechanism to prevent concurrent access to state file; platform-specific (fcntl/msvcrt)

**Force Push**
: Git operation that overwrites remote history; used when amending commits

## G

**Generic Command**
: Command like `agdt-set` that works with any key; requires single approval

## H

**hatch-vcs**
: Python build tool plugin that generates version from Git tags

## I

**Issue**
: Jira work item representing a task, bug, or feature

**Integration Test**
: Test that verifies interaction between multiple components or external services

## J

**Jira**
: Atlassian's issue tracking and project management platform

**JSON**
: JavaScript Object Notation; format used for state file

## L

**Lock Timeout**
: Maximum time to wait for file lock before failing; default 5 seconds

## M

**Mermaid**
: Text-based diagramming tool with GitHub support

**Multi-worktree**
: Git feature allowing multiple working directories for same repository

## N

**Namespace**
: Prefix for state keys to group related values (e.g., `jira.*`)

## P

**Parameterless Command**
: Command that reads parameters from state instead of CLI arguments

**PAT**
: Personal Access Token; authentication credential for APIs

**Prompt File (Workflow)**
: Markdown file that serves as the source of truth for a workflow step's Copilot session
prompt. Template files live in `agentic_devtools/prompts/<workflow>/default-<step>-prompt.md`;
the canonical versions are attached to
[issue #867](https://github.com/ayaiayorg/agentic-devtools/issues/867#issuecomment-4055694012).
At runtime, variables are interpolated by `loader.py` (Jinja2) and the rendered prompt is
saved to the workflow state directory. A Copilot session is then started with a
workflow-specific bootstrap prompt that instructs the agent to run the first workflow
command: `agdt-get-next-workflow-prompt` for most workflows, or
`agdt-advance-workflow pull-request-overview` for the PR review workflow. The rendered
prompt is then loaded and displayed by that command.

**Pull Request (PR)**
: Code review request in Azure DevOps or GitHub

**PyPI**
: Python Package Index; public repository for Python packages

## Q

**Quality Goal**
: Non-functional requirement specifying desired system quality (e.g., usability)

## R

**Repository Root**
: Top-level directory of Git repository; detected via `git rev-parse --show-toplevel`

**Runtime View**
: Documentation showing system behavior at runtime via scenarios and sequence diagrams

## S

**State File**
: `agdt-state.json` file storing all command parameters and workflow state

**State Machine**
: Pattern for managing workflow steps with explicit transitions

**Subprocess**
: Independent process spawned by main process; used for background tasks

**Subtask**
: Jira work item that is a child of another issue

## T

**Task ID**
: Unique identifier for background task; format: UUIDv4 (e.g., `550e8400-e29b-41d4-a716-446655440000`)

**Task State**
: Metadata about background task (status, PID, logs, output file)

**Template**
: Prompt template for workflow steps, stored under `agentic_devtools/prompts/` (not `.github/prompts/`, which only contains Copilot Chat prompt stubs)

**Thread**
: Discussion thread on Azure DevOps pull request

**Twine**
: Python tool for uploading packages to PyPI

## U

**Unit Test**
: Test that verifies single function or class in isolation

**Upstream**
: Remote Git repository to which local branch publishes

## V

**Virtual Environment (venv)**
: Isolated Python environment with independent packages

**VS Code**
: Visual Studio Code; Microsoft's code editor with Copilot integration

## W

**Workflow**
: Multi-step process orchestrated by state machine (e.g., work-on-jira-issue)

**Worktree**
: Additional working directory for Git repository; shares `.git` directory

## Abbreviations

| Abbreviation | Full Term | Description |
|--------------|-----------|-------------|
| **ADO** | Azure DevOps | Microsoft's DevOps platform |
| **ADR** | Architecture Decision Record | Document recording architectural decision |
| **AI** | Artificial Intelligence | GitHub Copilot and similar assistants |
| **API** | Application Programming Interface | Interface for external services |
| **CI/CD** | Continuous Integration/Continuous Deployment | Automated build and deployment |
| **CLI** | Command-Line Interface | Terminal/shell interface |
| **JSON** | JavaScript Object Notation | Data format |
| **PAT** | Personal Access Token | Authentication credential |
| **PR** | Pull Request | Code review request |
| **PyPI** | Python Package Index | Python package repository |
| **REST** | Representational State Transfer | HTTP API architecture |
| **TDD** | Test-Driven Development | Development methodology |
| **UX** | User Experience | User interaction design |
| **VCS** | Version Control System | Git, SVN, etc. |

## Command Categories

### State Management Commands

| Command | Purpose |
|---------|---------|
| `agdt-set` | Set state key to value |
| `agdt-get` | Get state value by key |
| `agdt-delete` | Delete state key |
| `agdt-clear` | Clear all state |
| `agdt-show` | Display all state |

### Git Workflow Commands

| Command | Purpose |
|---------|---------|
| `agdt-git-save-work` | Stage, commit/amend, push/force-push |
| `agdt-git-stage` | Stage all changes |
| `agdt-git-push` | Push to origin |
| `agdt-git-force-push` | Force push to origin |
| `agdt-git-publish` | Publish branch upstream |

### Azure DevOps Commands

| Command | Purpose |
|---------|---------|
| `agdt-add-pull-request-comment` | Add PR comment |
| `agdt-approve-pull-request` | Approve PR |
| `agdt-create-pull-request` | Create new PR |
| `agdt-reply-to-pull-request-thread` | Reply to PR thread |
| `agdt-resolve-thread` | Resolve PR thread |
| `agdt-get-pull-request-threads` | Get all PR threads |
| `agdt-get-pull-request-details` | Get PR details and diff |

### File Review Commands

| Command | Purpose |
|---------|---------|
| `agdt-approve-file` | Approve a file in PR review |
| `agdt-request-changes` | Request changes on a file with suggestions |
| `agdt-request-changes-with-suggestion` | Request changes with code replacement suggestions |
| `agdt-mark-file-reviewed` | Mark a file as reviewed |

### Jira Commands

| Command | Purpose |
|---------|---------|
| `agdt-add-jira-comment` | Add comment to issue |
| `agdt-get-jira-issue` | Get issue details |
| `agdt-update-jira-issue` | Update issue fields |
| `agdt-create-epic` | Create new epic |
| `agdt-create-issue` | Create new issue |
| `agdt-create-subtask` | Create subtask |

### Background Task Commands

| Command | Purpose |
|---------|---------|
| `agdt-tasks` | List all tasks |
| `agdt-task-status` | Show task status |
| `agdt-task-log` | Display task log |
| `agdt-task-wait` | Wait for task completion |
| `agdt-tasks-clean` | Clean expired tasks |

### Workflow Commands

| Command | Purpose |
|---------|---------|
| `agdt-initiate-work-on-jira-issue-workflow` | Start Jira issue workflow (auto-launches Copilot session) |
| `agdt-initiate-pull-request-review-workflow` | Start PR review workflow (auto-launches Copilot session) |
| `agdt-initiate-create-jira-issue-workflow` | Start create Jira issue workflow (auto-launches Copilot session) |
| `agdt-initiate-create-jira-epic-workflow` | Start create Jira epic workflow (auto-launches Copilot session) |
| `agdt-initiate-create-jira-subtask-workflow` | Start create Jira subtask workflow (auto-launches Copilot session) |
| `agdt-initiate-update-jira-issue-workflow` | Start update Jira issue workflow (auto-launches Copilot session) |
| `agdt-initiate-apply-pr-suggestions-workflow` | Start apply PR suggestions workflow (auto-launches Copilot session) |
| `agdt-advance-workflow` | Manually advance workflow step |
| `agdt-get-next-workflow-prompt` | Get next step prompt |

## State Key Patterns

### Common Keys

| Key | Type | Description |
|-----|------|-------------|
| `pull_request_id` | int | Azure DevOps PR ID |
| `thread_id` | int | PR thread ID |
| `content` | str | Comment/reply content |
| `commit_message` | str | Git commit message |

### Jira Namespace

| Key | Type | Description |
|-----|------|-------------|
| `jira.issue_key` | str | Issue identifier (e.g., PROJECT-1234) |
| `jira.comment` | str | Comment text |
| `jira.summary` | str | Issue summary |
| `jira.description` | str | Issue description |
| `jira.project_key` | str | Project identifier |

### File Review Namespace

| Key | Type | Description |
|-----|------|-------------|
| `file_review.file_path` | str | File path in PR |
| `file_review.line` | int | Line number for comment |
| `file_review.suggestion` | str | Code suggestion |

### Workflow Keys

| Key | Type | Description |
|-----|------|-------------|
| `workflow.name` | str | Workflow identifier |
| `workflow.status` | str | active/completed |
| `workflow.step` | str | Current step name |
| `workflow.context` | dict | Workflow-specific data |

## Environment Variables

| Variable | Purpose | Required |
|----------|---------|----------|
| `AZURE_DEV_OPS_COPILOT_PAT` | Azure DevOps authentication (preferred) | For ADO commands |
| `AZURE_DEVOPS_EXT_PAT` | Azure DevOps authentication (fallback) | For ADO commands |
| `JIRA_COPILOT_PAT` | Jira bearer/PAT authentication | For Jira commands (default; used when `JIRA_AUTH_SCHEME` is unset or `bearer`) |
| `JIRA_AUTH_SCHEME` | Jira auth scheme: `bearer` (default) or `basic` | Optional; defaults to `bearer` |
| `JIRA_EMAIL` | Jira account email (basic auth only) | Only when `JIRA_AUTH_SCHEME=basic` |
| `JIRA_USERNAME` | Jira username (basic auth only) | Only when `JIRA_AUTH_SCHEME=basic` |

## File Locations

| Location | Purpose |
|----------|---------|
| `.agdt/workflows/…/state.json` | State file |
| `.agdt/workflows/…/*.json` | Command output files |
| `.agdt/workflows/…/background-tasks/logs/` | Background task logs |
| `.github/agents/` | Copilot Chat agent definitions |
| `.github/prompts/` | Copilot Chat prompt stubs |
| `agentic_devtools/prompts/` | Workflow prompt templates (rendered by CLI workflows) |
