citation-agent-spec

Agent Specification: Citation Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Citation Agent | | **ID** | research-citation-agent | | **Purpose** | Format citations in any of 9,000+ styles, build citation networks, back claims with references, and manage bibliographies | | **Lifecycle Stage** | Integration (Stage 4 of Research Framework) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Citation Agent bridges research sources and documentation artifacts by formatting citations, inserting references into SDLC documents, tracking claim coverage, and building citation networks. It supports 9,000+ citation styles via CSL (Citation Style Language), generates BibTeX/RIS exports for external tools, and maintains a claims index showing which assertions are backed by research and which need additional sources.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | Citation Formatting | Format citations in Chicago, APA, IEEE, and 9,000+ styles | NFR-RF-C-07 | | Claims Backing | Match claims to sources and insert inline citations | NFR-RF-C-05 | | Bibliography Generation | Create and maintain bibliography with deduplication | BR-RF-C-004 | | Citation Network | Build graph showing paper relationships | UC-RF-004 Alt-3 | | Claims Index | Track backed vs. unbacked claims across documents | NFR-RF-C-08 | | BibTeX/RIS Export | Export bibliography for LaTeX, Zotero, EndNote | UC-RF-004 Alt-2 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Auto-Back Claims | Semantic matching to automatically suggest citations | | DOI Validation | Verify DOI links resolve correctly | | Style Switching | Convert existing citations between styles | | Network Visualization | Generate citation graphs in DOT/JSON format |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | File operations, DOI validation | Execute | | Read | Access sources, SDLC documents | Read | | Write | Update documents, bibliography | Write | | Glob | Find documents containing claims | Read | | Grep | Search for claims in documents | Read |

External Resources

| Resource | Purpose | Source | |----------|---------|--------| | CSL Styles | Citation formatting templates | [Zotero Style Repository](https://www.zotero.org/styles) | | CSL Locale | Language-specific formatting | CSL Project | | Citation.js | JavaScript citation processor | npm package |

4. Triggers

Automatic Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Documentation Complete | Paper documented (UC-RF-003) | Add to citation pool | | Workflow Stage | UC-RF-008 initiates Stage 4 | Process integration tasks |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Single Citation | `aiwg research cite "claim" --source REF-XXX` | Insert one citation | | Auto-Back | `aiwg research cite --auto-back-claims` | Auto-match claims | | Export BibTeX | `aiwg research export-bib --format bibtex` | Export bibliography | | Visualize Network | `aiwg research visualize-network` | Generate citation graph | | Style Switch | `aiwg research cite --switch-style apa` | Convert citation style |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Claim Text | String (10-500 chars) | User command | Non-empty | | Source Identifier | REF-XXX | User command | Valid REF-XXX exists | | Citation Style | String or CSL file | Optional flag | Valid CSL style | | Target Document | File path | Optional flag | File exists in `.aiwg/` |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | Inline Citations | Markdown text | SDLC documents | Permanent | | Bibliography | Markdown | `.aiwg/research/bibliography.md` | Permanent | | BibTeX Export | BibTeX format | `.aiwg/research/bibliography.bib` | Permanent | | RIS Export | RIS format | `.aiwg/research/bibliography.ris` | Permanent | | Claims Index | Markdown table | `.aiwg/research/knowledge/claims-index.md` | Updated continuously | | Citation Network | JSON graph | `.aiwg/research/networks/citation-network.json` | Permanent |

Output Schema: Claims Index

# Claims Index

**Coverage:** 151/200 claims backed (75.5%)
**Last Updated:** 2026-01-25T16:30:00Z

| Claim | Status | Source | Document | Last Updated |
|-------|--------|--------|----------|--------------|
| Token rotation reduces CSRF risk by 80% | Backed | REF-025 | `.aiwg/architecture/software-architecture-doc.md:142` | 2026-01-25 |
| OAuth PKCE prevents authorization code interception | Backed | REF-025 | `.aiwg/requirements/nfr-modules/security.md:78` | 2026-01-25 |
| LLM caching reduces latency by 40% | Unbacked | - | `.aiwg/architecture/adr-008-llm-caching.md:23` | 2026-01-20 |

Output Schema: Citation Network JSON

{
  "nodes": [
    {
      "id": "REF-025",
      "title": "OAuth 2.0 Security Best Practices",
      "authors": ["Smith, J.", "Doe, J."],
      "year": 2023,
      "citation_count": 5,
      "grade_score": 90
    }
  ],
  "edges": [
    {
      "source": ".aiwg/architecture/software-architecture-doc.md",
      "target": "REF-025",
      "claim": "Token rotation reduces CSRF risk by 80%",
      "context": "supported",
      "timestamp": "2026-01-25T16:30:00Z"
    }
  ]
}

6. Dependencies

Agent Dependencies

| Agent | Relationship | Interaction | |-------|--------------|-------------| | Documentation Agent | Upstream | Receives extractions with claims | | Archival Agent | Downstream | Provides bibliography for packaging | | Workflow Agent | Orchestrator | Receives task assignments | | Provenance Agent | Observer | Logs citation operations |

Service Dependencies

| Service | Purpose | Fallback | |---------|---