Draftspec: A Lightweight Structured Document Specification for AI Agent Workflows in Legacy Systems

Draftspec is a strict yet lightweight structured document definition (SDD) specification designed for AI Agent workflows in legacy systems. It addresses the challenges of integrating AI Agents into brownfield systems (lack of complete docs, inconsistent interfaces, scattered business logic) by balancing strictness (machine-verifiable) and lightness (supports fast iteration). Key aspects include agent workflow orientation, legacy system adaptability, and a supporting toolchain. This post breaks down its design, structure, applications, and best practices.

As enterprises adopt AI Agents for automation, most face brownfield projects (existing legacy systems) instead of greenfield ones. Legacy systems often lack comprehensive documentation, have inconsistent interfaces, and scattered business logic—creating barriers to AI Agent integration. Traditional SDDs are too heavy, requiring significant upfront effort and maintenance, which becomes a bottleneck for fast AI Agent iterations. Draftspec was developed to solve these issues.

Draftspec is an open-source structured document specification for AI Agent-legacy system integration, with the core idea: 'Strict enough to ensure correctness, lightweight enough to support rapid iteration'. Its key principles:

1. Agent workflow oriented: Focuses on the Observation-Thought-Action loop (context management, tool chains, decision logic, state transitions).
2. Strict but lightweight: Uses a strict type system (basic types, enums, structs) and YAML-like syntax for readability, with Schema validation tools.
3. Legacy-friendly: Provides interface mapping (for inconsistent legacy interfaces), data conversion rules, and progressive adoption support. Unlike OpenAPI, it covers workflow orchestration beyond static API definitions.

Draftspec documents include:

• Header: Version, title, description, target system, tags.
• Context: Session (cross-tool), turn (single interaction), persistent (cross-session) contexts—each with type, required status, default values, validation rules.
• Tools: Core part—name, description (for Agent decision), parameters, returns, errors, side effects (critical for safe Agent design).
• Workflow: Entry point, steps (tool calls, branches, sub-workflows), transitions, termination conditions (supports sequence, parallel, conditional branches).
• Error Handling: Error types, handlers (retry, degrade, terminate), global fallback strategy.

Draftspec is applied in:

1. Legacy CRM: Unify scattered interfaces, define tools (customer query, order creation), orchestrate workflows like complaint handling, generate SDKs.
2. Enterprise Knowledge Base: Unify retrieval interfaces, data fusion strategies, answer generation rules, access control and sensitive info filtering.
3. DevOps: Encapsulate CI/CD/monitoring interfaces, define security constraints (e.g., no direct production config changes), orchestrate operation and maintenance workflows (fault diagnosis, auto-scaling), record audit logs.

• vs OpenAPI: OpenAPI focuses on single API endpoints; Draftspec covers cross-API workflow orchestration for Agents.
• vs LangChain/LangGraph: Draftspec is a high-level doc abstraction (non-technical friendly) vs code-level framework (can be combined: Draftspec for design, LangChain for implementation).
• vs BPMN: BPMN is complex and not Agent-focused; Draftspec simplifies syntax and adds Agent-specific concepts (tools, context).

Draftspec provides a complete toolchain:

• Validator: CLI tool for syntax/semantic checks (type consistency, tool reference integrity, loop detection).
• Code Generator: Generates Agent adapter code, type definitions (TypeScript/Python), test stubs, doc sites.
• IDE Plugins: VS Code support (syntax highlight, auto-completion, real-time errors, jump to definition).
• Runtime Libraries: Load/parse docs, context management, tool routing, workflow execution engine.

Best Practices:

1. Progressive adoption (start with frequent modules, expand gradually).
2. Version control (docs in VCS, code review for changes, compatibility checks for major versions).
3. Collaboration (business experts define workflows, devs write docs, maintainers review feasibility).
4. Test based on docs (contract tests, parameter boundary checks, error path testing). Future Directions: Multi-Agent collaboration support, enhanced security/compliance (data desensitization, access control), performance modeling (latency, cost), visual doc editor.