# Agentic Development Tools (AGDT) — Framework Overview

> Positions AGDT as a core building block of Swica's **AI Factory**.

---

## 1. Executive Summary

**Agentic Development Tools (AGDT)** is Swica's home-grown framework that lets AI
coding agents (GitHub Copilot in VS Code) perform real software-engineering work
**reliably, repeatably and safely** — not just generate code snippets, but drive
whole workflows: picking up an issue, planning it, implementing it with tests,
reviewing the pull request, and closing the loop back to Jira / Azure DevOps.

The core idea is simple but powerful:

- Agents are unreliable when they improvise multi-step processes (raw `git`, raw
  REST calls, ad-hoc shell scripts). They stall, they hallucinate, they skip steps.
- AGDT replaces improvisation with a **library of small, deterministic,
  auto-approvable CLI "macros"** (`agdt-*`). Each encodes an established practice
  or convention once, and every agent reuses it the same way, every time.

The result is a **paved road for agentic development**: the agent stays productive
and on-rails, the human stays in control, and the organisation's best practices are
baked into the tooling instead of living in people's heads.

> **One-line pitch:** *AGDT turns Swica's development conventions and best
> practices into reusable functions that AI agents can execute safely — the
> operating layer that makes "AI Factory" repeatable at scale.*

### Why it matters for AI Factory

AI Factory is Swica's dedicated team for building software **with AI across any
domain**. The bottleneck for that ambition is **not** model quality — it is
**consistency, governance and reuse**. AGDT is the layer that provides exactly
that: a shared, versioned set of conventions and automations that any team, any
repo and any agent can plug into on day one.

Where AGDT sits:

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
flowchart BT
    L1["🤖 <b>AI capability</b><br/>GitHub Copilot / LLM agents in VS Code"]
    L2["⚙️ <b>AGDT — the operating layer</b><br/>agdt-* macros · workflows · conventions · guardrails · MCP"]
    L3["🏭 <b>AI Factory</b><br/>build software across any Swica domain<br/>reliable · conventional · governed, at scale"]
    L1 --> L2 --> L3
```

---

## 2. The Problem We Are Solving

| Without AGDT | With AGDT |
|---|---|
| Agents run raw `git`, stall on prompts, create messy history | One `agdt-git-save-work` macro: stage → commit/amend → push, in the background |
| Each dev/agent re-invents PR review, Jira updates, branch naming | Shared workflows encode the convention once |
| Best practices live in wikis nobody reads | Best practices are **executable** and enforced by tooling |
| VS Code asks to approve every command → friction, fatigue | Generic `agdt-set` + parameterless actions → **approve once, reuse everywhere** |
| Long operations block the agent → it thinks it failed → retries | Background tasks return immediately with a task ID |
| Special characters / multiline break shell escaping | Native Python handling, no token juggling |

The unifying insight: **make the correct, conventional path the easiest path** —
for both humans and agents.

---

## 3. What AGDT Is (Current Status)

AGDT is a **pip-installable Python package** exposing dozens of `agdt-*` CLI
commands, plus:

- **Copilot Chat agents & prompts** — every command has a matching `/agdt.*`
  chat agent, so workflows can be launched conversationally in VS Code.
- **An MCP server** — the same tools are exposed over the **Model Context
  Protocol**, so *any* MCP-compatible agent (not just Copilot) can discover and
  call them.
- **A state machine + workflow engine** — multi-step workflows (e.g. "work on a
  Jira issue" = 11 steps) that auto-advance as the agent completes each stage.
- **Spec-Driven Development (SDD / speckit)** integration — `specify → plan →
  tasks → implement` for structured feature delivery.

### High-level architecture

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
graph TB
    subgraph IDE["Developer IDE — VS Code"]
        Dev["👩‍💻 Developer"]
        Copilot["🤖 GitHub Copilot<br/>(Chat + Agent mode)"]
    end

    subgraph AGDT["AGDT Framework"]
        Agents["/agdt.* Chat Agents<br/>& Prompts"]
        CLI["agdt-* CLI commands<br/>(the 'macros')"]
        WF["Workflow Engine<br/>(state machine)"]
        State["JSON State Store<br/>(per-worktree)"]
        BG["Background Task<br/>Runner"]
        MCP["MCP Server<br/>(protocol bridge)"]
    end

    subgraph Ext["Integrated Services"]
        Git["Git / GitHub"]
        ADO["Azure DevOps"]
        Jira["Jira"]
        AI["App Insights / Azure"]
        PyPI["PyPI"]
    end

    Dev --> Copilot
    Copilot --> Agents
    Agents --> CLI
    Copilot -.MCP.-> MCP
    MCP --> CLI
    CLI --> WF
    CLI --> State
    CLI --> BG
    WF --> State
    BG --> Git & ADO & Jira & AI & PyPI
```

### Command families available today

| Domain | Examples | Purpose |
|---|---|---|
| **State** | `agdt-set`, `agdt-get`, `agdt-show` | Approve-once generic state; the auto-approval trick |
| **Git** | `agdt-git-save-work`, `agdt-git-publish`, `agdt-git-force-push` | Safe, single-commit-per-PR git flow |
| **Azure DevOps** | `agdt-create-pull-request`, `agdt-initiate-pull-request-review-workflow`, `agdt-reply-to-pull-request-thread` | PR lifecycle + automated code review |
| **GitHub** | `agdt-gh-pr-poll-ready`, `agdt-gh-pr-merge`, `agdt-gh-copilot-review-status` | PR CI/merge automation |
| **Jira** | `agdt-get-jira-issue`, `agdt-add-jira-comment`, `agdt-create-epic` | Issue tracking as first-class workflow |
| **Azure / Ops** | `agdt-query-app-insights`, `agdt-query-fabric-dap-errors` | Log crawling & incident analysis |
| **Workflows** | `agdt-initiate-work-on-jira-issue-workflow`, `agdt-advance-workflow` | Multi-step orchestration |
| **Testing** | `agdt-test`, `agdt-test-file` | Background test runs with coverage gates |

### Flagship workflows (working today)

1. **Work on a Jira issue** (11-step state machine): setup worktree → fetch issue
   → plan → checklist → implement (TDD) → review → verify → commit → PR → close.
2. **Automated PR review**: fetches diff + threads + linked issue, reviews each
   file with an agent, posts a consolidated per-commit review comment, and marks
   files as reviewed in the PR UI.
3. **Address review feedback / auto-merge loop**: poll CI, address Copilot review
   comments, approve, and merge when green.
4. **Spec-Driven Development**: turn a natural-language feature request into a
   spec, plan, task list and implementation.

---

## 4. How We Work Today: The AGDT-Driven Development Cycle

This is the loop we run **right now**. We use **Jira** for story/task tracking —
but the model is deliberately **tracker-agnostic**: the same cycle works with plain
Markdown files in the repo, GitHub Issues, or another tool, because agents call
`agdt-*` commands rather than any one provider's API.

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    A["📝 Create issue<br/><i>agdt-initiate-create-jira-issue-workflow</i>"]
    B["✨ Optimize for AI agent<br/><i>agdt-initiate-optimize-issue-for-ai-agent-workflow</i>"]
    C["👤 Assign to agent<br/><i>agdt-assign-implementation-agent</i>"]
    D["🛠️ Agent implements<br/><i>agdt-initiate-work-on-jira-issue-workflow</i>"]
    E["🔍 Automated PR review<br/><i>agdt-initiate-pull-request-review-workflow</i>"]
    G["👥 Human review<br/>(required sign-off)"]
    F["✅ Merge when green<br/>& approved"]

    A --> B --> C --> D --> E --> G --> F
    E -. "changes requested" .-> D
    G -. "changes requested" .-> D
    F -. "next story" .-> A
```

| Stage | AGDT command / agent | What it does |
|---|---|---|
| **1. Create issue** | `agdt-initiate-create-jira-issue-workflow` (`/agdt.create-jira-issue.initiate`) | Capture a story/task with a well-formed, structured description |
| **2. Optimize for AI** | `agdt-initiate-optimize-issue-for-ai-agent-workflow` (`/agdt.optimize-issue-for-ai-agent.initiate`) | Rewrite the issue into an **implementation-ready spec** an agent can act on (acceptance criteria, scope, context) |
| **3. Assign to agent** | `agdt-assign-implementation-agent` | Hand the refined issue to a coding agent (e.g. the Copilot coding agent) to start work |
| **4. Implement** | `agdt-initiate-work-on-jira-issue-workflow` | The 11-step workflow: worktree → plan → checklist → TDD implementation → verify → commit → PR |
| **5. Automated PR review** | `agdt-initiate-pull-request-review-workflow` (`/agdt.pull-request-review.initiate`) | Automated, per-file review posting a consolidated per-commit comment |
| **6. Human review (required)** | Human reviewer + `agdt-*` reply/approve commands | **Mandatory human sign-off** — every PR is reviewed by a person before it can merge (human-in-the-loop gate) |
| **7. Close the loop** | auto-merge loop (`agdt-gh-pr-poll-ready` → `agdt-gh-pr-merge`) | After approval, poll CI, and merge when green |

**Human-in-the-loop is a hard gate, not optional:** the automated review accelerates
and standardises the first pass, but **every PR still requires a human reviewer's
approval before merge.** The agent does the heavy lifting (per-file analysis,
consolidated comments); the human owns the final judgment call.

**Why "optimize-issue-for-ai-agent" is the pivotal step:** agent output quality is
bounded by input quality. Turning a rough ticket into a precise, self-contained spec
is what makes autonomous implementation reliable — it is the human-judgment gate
before we hand work to a machine.

### Where This Is Heading — From Assisted Steps to Orchestrated Agents (LangGraph)

Today each stage is a **discrete command a human triggers** (an *assisted* loop).
The next step is to **orchestrate these stages into autonomous, resumable pipelines**
using **[LangGraph](https://langchain-ai.github.io/langgraph/)** — already a
dependency and foundation in the codebase (`agentic_devtools/orchestration/`,
`--engine langchain`, with SQLite checkpointing). The direction is formally set in
the project's architecture decisions: **ADR-013** (LangGraph as the orchestration
framework) and **ADR-014** (the autonomous execution model). AGDT is deliberately
evolving *from a CLI helper tool into a full workflow-orchestration layer*.

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    subgraph Now["Today — assisted"]
        H1["Human triggers each<br/>agdt-* command"]
    end
    subgraph Next["Soon — orchestrated"]
        G["LangGraph graph<br/>drives the cycle"]
        G --> N1["nodes = AGDT<br/>tool functions"]
        G --> N2["checkpointing<br/>= resumable"]
        G --> N3["interrupts =<br/>human-in-the-loop gates"]
    end
    H1 -. "same tools, now graph-orchestrated" .-> G
```

What LangGraph orchestration adds on top of the existing macros:

- **Autonomous multi-step runs** — the graph moves an issue from *created* to
  *merged* with agents at each node, pausing only at defined **human-in-the-loop
  interrupts** (e.g. approve the spec, approve the merge).
- **Resumability** — checkpointed state means a long-running pipeline can stop,
  survive a crash, and resume exactly where it left off.
- **Same tools, higher leverage** — the LangGraph nodes call the **same `agdt-*`
  tool functions** exposed via the MCP layer, so all our conventions and guardrails
  carry over. We are raising the *orchestration* level, not rebuilding the toolset.

**Target architecture (per ADR-013 / ADR-014):**

- **Multiple agents on one issue over hours or days** — durable, per-issue state
  (LangGraph `SqliteSaver` checkpointing) that survives across sessions.
- **Deliberative multi-reviewer consensus** — sequential reviewers with a "boss"
  escalation pattern for contested decisions, instead of a single-pass review.
- **Deterministic, application-controlled routing** — *the AI never decides the
  routing*; nodes are focused functions that receive prepared context. Agents
  reason and generate; the graph decides what runs next.
- **Configurable human-in-the-loop gates** — `interrupt()` / resume primitives make
  the approval points explicit and configurable per workflow.
- **Structured, timestamped audit trail** — every step is checkpointed, giving a
  reproducible record of what each agent did and why.

> **Progression:** manual commands → assisted workflows (today) → **LangGraph-orchestrated
> agentic pipelines (next)** — with humans supervising by exception rather than driving
> every step.

---

## 5. The Convenience-Function Vision (Where We're Going)

Today's commands are the first slice. The **strategic intent** is a **broad and
growing catalogue of convenience functions** that capture reusable engineering
knowledge — so that "doing it right" is a single command. Illustrative examples:

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
graph LR
    Root(["AGDT<br/>convenience<br/>functions"])

    Root --> Doc["📄 Documentation"]
    Doc --> D1["Keep docs in sync with code"]
    Doc --> D2["Auto-generate architecture views"]
    Doc --> D3["Detect stale README / ADRs"]

    Root --> Iss["🔎 Issue analysis"]
    Iss --> I1["Crawl App Insights logs"]
    Iss --> I2["Correlate traces to a Jira issue"]
    Iss --> I3["Draft reproduction + root cause"]

    Root --> Best["✅ Best-practice checks"]
    Best --> B1["Design principles (SOLID, DDD)"]
    Best --> B2["Tech-stack design patterns"]
    Best --> B3["Security / OWASP scans"]

    Root --> Agent["🤖 Agentic-readiness of a repo"]
    Agent --> A1["Required dirs & files present"]
    Agent --> A2["copilot-instructions.md up to date"]
    Agent --> A3["AGENTS.md / skills / prompts valid"]

    Root --> Hyg["🧹 Delivery hygiene"]
    Hyg --> H1["One-commit-per-PR"]
    Hyg --> H2["Conventional commits + issue refs"]
    Hyg --> H3["Branch naming conventions"]
```

### Concrete near-term candidates

- **Documentation freshness** — verify docs/ADRs still match the code; flag drift.
- **Issue triage from telemetry** — given an error, crawl App Insights, gather the
  traces, and pre-populate an analysis so the agent starts from evidence, not guesses.
- **Repository best-practice audit** — check that a repo follows the design
  principles and patterns appropriate to its tech stack.
- **Agentic-readiness lint** — verify a repo is *set up for productive agent work*:
  the right `copilot-instructions.md`, `AGENTS.md`, instruction/prompt/skill files,
  directory layout, and file formats that Copilot in VS Code relies on.

Each new function follows the same recipe: **encode an established practice once,
expose it as an auto-approvable macro, and let every agent and team reuse it.**

---

## 6. Why Repo Hygiene & Copilot/VS Code Conventions Are Central

VS Code is our development IDE, and **GitHub Copilot's effectiveness is directly
proportional to how well the repository is structured for it.** Copilot reads:

- `copilot-instructions.md` / `AGENTS.md` — project conventions & guardrails
- `.github/instructions/*.instructions.md` — path-scoped rules (`applyTo`)
- `.github/prompts/*` and `.github/agents/*` — reusable prompts & agent modes
- **Skills** — packaged domain knowledge the agent loads on demand

If these are missing, outdated, or malformed, the agent improvises — and quality
drops. Therefore a **core AGDT concern is keeping the git repository continuously
aligned with the latest Copilot-in-VS-Code guidelines and best practices**:

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    A["Repo follows latest<br/>Copilot/VS Code conventions"] --> B["Agent has correct<br/>context & guardrails"]
    B --> C["Higher-quality,<br/>on-convention output"]
    C --> D["Less human rework,<br/>faster delivery"]
    D --> A
    E["AGDT audit &<br/>maintenance macros"] -.keeps.-> A
```

AGDT's role is to **automate this hygiene**: detect when instruction files drift
from current best practice, validate that required files/formats are present, and
(increasingly) fix them. Well-kept guidelines are not bureaucracy — they are the
**input that determines agent output quality**.

---

## 7. Design Principles That Make It Work

1. **Auto-approvable by design** — one generic `agdt-set key value` + parameterless
   actions means VS Code approves the *pattern* once, not every invocation.
2. **State-driven, not argument-driven** — a single per-worktree JSON state file
   carries context between steps; multiple worktrees stay fully isolated.
3. **Background-first** — long operations return immediately with a task ID so the
   agent never mistakes "still running" for "failed".
4. **Provider-agnostic** — agents call `agdt-*`, never raw `gh`/`az`/REST, so the
   same workflow works across GitHub, Azure DevOps and Jira.
5. **Convention as code** — best practices (single-commit PRs, conventional commits,
   TDD, 1:1:1 test structure, 100 % branch coverage) are enforced by tooling, not memory.
6. **Structured preparation over runtime discovery** — a two-phase pattern:
   deterministic context-gathering first, then focused agent evaluation. This is
   reproducible, audit-traceable, and cuts token use materially (Constitution XII).
7. **Provider-native files stay thin** — CI/pipeline YAML is a minimal dispatch
   wrapper around one `agdt-*` command; business logic lives in testable code, not
   vendor-locked YAML (Constitution XIV).
8. **Testable & governed** — the framework is built to its own standards (TDD,
   coverage gates, pre-push hooks) and to a written **15-principle constitution**,
   so the operating model itself is codified, not tribal knowledge.

---

## 8. Beyond the Technical Layer: Organisational & Transformational Fit

The technical substrate is only part of the story — the operating model around it
matters just as much.

AGDT is as much an **operating model** as a toolset:

- **A paved road** — teams adopt shared conventions by adopting the tools, lowering
  onboarding cost and variance across the AI Factory portfolio.
- **Governance & auditability** — every agent action goes through named commands,
  which are logged, dry-run-able and reviewable. This is how we make agentic work
  **safe to scale** across domains and teams.
- **Human-in-the-loop by construction** — hard-to-reverse actions require
  confirmation; the agent is on-rails but the human stays in control.
- **Knowledge capture** — when a team discovers a better practice, it becomes a new
  AGDT function and instantly benefits everyone. The framework is a living,
  compounding asset.
- **Codified governance** — the operating model is written down: a **15-principle
  constitution** plus **Spec-Driven Development** (every feature starts as a
  reviewed spec). Governance is a document teams can adopt, not folklore.
- **Change management** — adoption is incremental (a repo can start with one macro),
  which suits a transformation rolled out team-by-team.

**The compounding flywheel** — capturing each practice once makes AGDT an asset that
grows in value with every team that uses it:

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
    A["Team discovers a<br/>better practice"] --> B["Encode it once as<br/>an agdt-* function"]
    B --> C["Every agent & team<br/>reuses it instantly"]
    C --> D["Higher quality,<br/>less variance"]
    D --> A
```

---

## 9. Roadmap / Intention

| Horizon | Focus |
|---|---|
| **Now** | Core workflows (Jira issue, PR review, auto-merge, SDD); Git/ADO/Jira integration; MCP server; auto-approval UX |
| **Next** | Expand the convenience-function catalogue (docs-freshness, telemetry-driven issue analysis, repo best-practice & agentic-readiness audits); grow the **LangGraph** orchestration layer (ADR-013/014) with resumable, checkpointed pipelines |
| **Later** | Deliberative multi-agent review with boss escalation; phased state consolidation (JSON → SQLite) with per-issue audit trails; broader provider coverage; self-maintaining repo hygiene (detect → propose → fix); optional plugin system, containerised execution, and a web UI for state inspection |

> **How features get built:** each item is delivered via **Spec-Driven Development** —
> it starts life as a reviewed spec under `specs/` (spec → plan → tasks → implement),
> so the roadmap is a pipeline of concrete, traceable specifications, not a wish list.

**Direction of travel:** from *"macros that help an agent do one task"* toward *"a
standardised, governed platform that makes every AI Factory team productive on any
repo from day one, while continuously keeping repos aligned with the latest Copilot
best practices."**

---

## 10. Key Messages

1. **AGDT = the operating layer for AI Factory.** Models write code; AGDT makes
   agentic *engineering* reliable, conventional and safe to scale.
2. **Convention-as-code.** Best practices become reusable, auto-approvable functions —
   captured once, reused by every agent and team.
3. **Repo hygiene is a first-class concern.** Keeping repos aligned with the latest
   Copilot-in-VS-Code conventions is what determines agent output quality — and AGDT
   automates that hygiene.
4. **It's a platform *and* an operating model.** The transformational/organisational
   layer (paved road, governance, knowledge capture) is as important as the tech.
5. **Concrete and running today**, with a clear, expanding roadmap of convenience
   functions — including telemetry-driven issue analysis relevant to questions like
   "how do we support operational activities with agents?"

---

## 11. Wiki Placement (Confluence)

**Canonical home:** **KI Services → Agentic Dev Tools** — a new page beside
*"Einsatzkonzept für GitHub Copilot Business"*. AGDT is a **tooling / service
capability**, so it belongs with KI Services, not with deployed domain agents.

- **This overview + the one-pager** live on the *Agentic Dev Tools* landing page.
- **Cross-link (don't duplicate)** from **AI Konzepte** — AGDT is the platform behind
  *"SDD Worker: Governed Vibe Coding"* — and, if the arc42 docs are published, from
  **Architektur AI** (Bausteinsicht ← building blocks, Entwurfsentscheidungen ← ADRs,
  Qualitätsanforderungen ← quality requirements).
- **Not under KI Inventory** — that section is for *named domain agents* (Alexa, Berta,
  Hanno); AGDT is the tooling they are built with, so leave only a pointer there.
- **Long-term:** may move to a top-level **AI Tools** section if a multi-tool family
  emerges; a Confluence page move preserves history and links, so starting under
  KI Services costs nothing.

---

*See also: [`agdt-onepager.md`](agdt-onepager.md) for a condensed,
presentation-ready summary.*
