# AGDT — One-Pager

> Condensed talking points for AGDT.
> Full detail: [`agdt-framework-overview.md`](agdt-framework-overview.md).

---

## The Pitch (30 seconds)

> **Agentic Development Tools (AGDT)** is Swica's framework that turns our
> development conventions and best practices into **reusable, auto-approvable
> functions that AI agents (Copilot in VS Code) can execute reliably.**
> It is the **operating layer that makes "AI Factory" repeatable and safe at scale** —
> the technical substrate *and* the paved road / operating model around it.

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff', 'clusterBorder':'#b0b0b0', 'clusterBkg':'#d4e8fb', 'primaryColor':'#ffe9b3'}}}%%
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
```

---

## The Problem → The Answer

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff', 'clusterBorder':'#b0b0b0', 'clusterBkg':'#d4e8fb', 'primaryColor':'#ffe9b3'}}}%%
flowchart LR
    P["❌ <b>Agents improvise multi-step work</b><br/>raw git · raw APIs · ad-hoc scripts<br/>→ stall, skip steps, messy history"]
    A["✅ <b>AGDT: a paved road of macros</b><br/>small, deterministic agdt-* commands<br/>→ same correct path, every time"]
    P -->|"AGDT"| A
```

Make the **correct, conventional path the easiest path** — for humans and agents alike.

---

## What Exists Today

- **Dozens of `agdt-*` CLI macros** across Git, Azure DevOps, Jira, Azure/App Insights.
- **Copilot Chat agents** (`/agdt.*`) + an **MCP server** so any agent can use them.
- **Multi-step workflows** that auto-advance: work-on-Jira-issue (11 steps),
  automated PR review, auto-merge loop, Spec-Driven Development.
- Built to its own standards: TDD, 100 % branch coverage, one-commit-per-PR.

---

## How We Work Today (tracker-agnostic — Jira today, could be files/other)

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff', 'clusterBorder':'#b0b0b0', 'clusterBkg':'#d4e8fb', 'primaryColor':'#ffe9b3'}}}%%
flowchart LR
    A["📝 create-issue"]
    B["✨ optimize-issue-for-ai-agent"]
    C["👤 assign-issue"]
    D["🛠️ implement"]
    E["🔍 automated PR-review"]
    F["👥 human review<br/>(required)"]
    G["✅ merge"]
    A --> B --> C --> D --> E --> F --> G
    E -. "changes requested" .-> D
    F -. "changes requested" .-> D
    G -. "next story" .-> A
```

- **Optimize-for-AI** is the pivotal, human-judgment step: rough ticket → precise,
  implementation-ready spec (agent output quality = input quality).
- **Human review stays mandatory**: automated PR review does the first pass, but
  **every PR requires a human sign-off before merge** (human-in-the-loop gate).
- **Soon — agentic orchestration with LangGraph** (already a dependency; direction set
  in ADR-013/014): the same `agdt-*` tools become **nodes in a resumable graph** with
  **human-in-the-loop interrupts**. Target: **multiple agents on one issue over
  hours/days** (durable checkpointed state), **deliberative multi-reviewer consensus**
  with boss escalation, **deterministic routing (the AI never routes)**, and a
  **structured audit trail**. Progression: *manual → assisted (today) → orchestrated.*

---

## The Vision — A Growing Catalogue of Convenience Functions

Encode each established practice **once**, expose it as a macro, reuse everywhere:

| Category | Example functions (illustrative) |
|---|---|
| 📄 Documentation | Keep docs in sync with code; flag stale ADRs/README |
| 🔎 Issue analysis | Crawl App Insights logs for an error → draft root-cause note |
| ✅ Best-practice checks | Design principles & patterns per tech stack; security |
| 🤖 Agentic-readiness | Verify `copilot-instructions.md`, `AGENTS.md`, skills, dirs & formats |
| 🧹 Delivery hygiene | Conventional commits, branch naming, single-commit PRs |

---

## Why Repo Hygiene Matters (a core theme)

VS Code + Copilot is our IDE. **Copilot's output quality ≈ how well the repo is set
up for it** (instruction files, prompts, agents, skills, layout, formats).

```mermaid
%%{init: {'theme':'base', 'themeVariables': {'lineColor':'#888888', 'edgeLabelBackground':'#ffffff', 'clusterBorder':'#b0b0b0', 'clusterBkg':'#d4e8fb', 'primaryColor':'#ffe9b3'}}}%%
flowchart TB
    A["Repo aligned with latest<br/>Copilot/VS Code best practices"]
    B["Agent gets correct<br/>context + guardrails"]
    C["Higher-quality, on-convention<br/>output → less rework"]
    A --> B --> C
```

AGDT automates keeping repos aligned — hygiene is an **input to quality**, not overhead.

---

## Organisational / Transformational Angle

- **Paved road** → lower onboarding cost, less variance across teams.
- **Governance & auditability** → every agent action is a named, logged, dry-run-able command.
- **Human-in-the-loop** → hard-to-reverse actions need confirmation.
- **Compounding knowledge** → a better practice discovered once becomes a function for all.
- **Codified governance** → written **15-principle constitution** + **Spec-Driven
  Development** (every feature starts as a reviewed spec) — governance as a document, not folklore.
- **Incremental adoption** → suits a team-by-team transformation.

---

## Five Messages to Land

1. AGDT = **operating layer for AI Factory** (not just codegen).
2. **Convention-as-code**: best practices → reusable functions.
3. **Repo hygiene is first-class** and drives agent quality.
4. It's a **platform *and* an operating model** (tech + transformation).
5. **Running today**, with a clear roadmap — incl. telemetry-driven issue analysis
   relevant to questions like "how do we support operational activities with agents?"

---

## Wiki Placement

**Home:** **KI Services → Agentic Dev Tools** (beside *"Einsatzkonzept für GitHub
Copilot Business"*). Cross-link from **AI Konzepte** (*SDD / Governed Vibe Coding*);
leave only a pointer under **KI Inventory** (that section is for named domain agents).
Full rationale in the overview.
