DEV Community: Luis Cruz

Intent to Specs: Agentic Specification Protocol

Luis Cruz — Thu, 26 Mar 2026 01:56:10 +0000

As an architect, engineer or analyst, your goal is to create a "Contract" between the business intent and the machine execution.

Below is a proposed methodology: the Agentic Specification Protocol (ASP), to bridge the gap between high-level business requirements and the technical implementation of LLM agents, we need to evolve the way we communicate our intents.

Let's explore how to transform the Trinity Framework (Task, Context, Constraint) from a simple prompting technique into a structured Business Analysis & Specification (BA&S) methodology.

1. The ASP Hierarchy: From Business Need to Agent Spec

In traditional software, we move from User Stories to Technical Specs. In LLM-centric systems, we move from Business Intent to Trinity-Mapped Modules.

Phase 1: Contextual Engineering (The Foundation)

Business analysis usually starts with "what" we want to do, but for LLMs, "where" the agent lives is more important.

Domain Mapping: Define the specific universe of knowledge. (e.g., "The agent is a Junior Underwriter for specialized marine insurance.")
Knowledge Retrieval (RAG) Definition: Identify the specific data sources the agent has access to. A spec is useless if the LLM doesn't know its "source of truth."
Persona Calibration: Define the voice and authority level.

Phase 2: Task Decomposition (The Logic)

Business tasks are often too broad ("Handle customer complaints"). For an agent, we must decompose these into Atomic Cognitive Tasks.

Step-by-Step Chain of Thought (CoT): Define the reasoning path.
Input/Output Schemas: Specify exactly what data enters the system and the JSON/Markdown structure required for the exit.

Phase 3: Constraint Guardrailing (The Safety)

Constraints are the most overlooked part of BA. In this framework, constraints are treated as Hard Barriers and Soft Guidelines.

Negative Constraints: Explicitly list what the LLM cannot do (e.g., "Never mention competitors," "Do not offer legal advice").
Operational Latitudes: Define the "hallucination tolerance"—is this a creative task or a zero-error extraction task?

2. The Trinity Specification Template (TST)

When conducting business analysis interviews, use this template to capture requirements. This document becomes the "Source of Truth" for developers and agent-orchestrators.

Pillar	Specification Field	Description
CONTEXT	System Persona	The specific role, expertise level, and tone.
	Environment/Tools	APIs, Databases, or Python environments the agent can access.
	Reference Data	The documentation or context window limits.
TASK	Primary Objective	The singular "Definition of Done" for the agent.
	Workflow (Steps)	The logical sequence (Step 1: Categorize, Step 2: Extract, Step 3: Validate).
	Success Criteria	How a human evaluator knows the task was performed correctly.
CONSTRAINT	Output Format	JSON Schema, Pydantic Model, or specific Markdown headers.
	Negative Guardrails	"Under no circumstances shall the agent..."
	Handling Uncertainty	Explicit instructions for when the agent doesn't know the answer.

3. Workflow for Developers & Agents

Once the BA provides the Trinity Specification, the Software Architect transforms it into a System Prompt Package.

Step A: Prompt Templating

The developer takes the Context and Constraint sections and hardcodes them into the System Message. This ensures the agent's behavior is immutable across sessions.

Step B: Tool/Function Definition

If the Task section requires "Checking a database," the developer maps that specific sub-task to a function call.

Step C: Implementation Specs for Agents

For multi-agent systems, the "Task" of one Trinity Spec becomes the "Context" for the next.

Agent A (The Classifier): Task is to route the request.
Agent B (The Specialist): Task is to process the routed request using its specific Context.

4. Why this works for Architects

Eliminates Ambiguity: Business users often give vague tasks. This framework forces them to define the "Constraints" (The "No-Go" zones), which is where most LLM projects fail.
Modular Scalability: If the business logic changes, you only update the "Task" pillar. If the company tone changes, you only update the "Context."
Auditability: You can evaluate an LLM's performance specifically against the "Constraint" pillar, making automated testing (LLM-as-a-judge) much easier to implement.

Recommendation

Create a standardized Markdown template based on the Trinity Framework and mandate its use for all "Feature Requests" involving AI. This ensures that by the time a ticket reaches a developer, 80% of the prompt engineering is already done.

That 80% isn't a hard statistic from a white paper; it’s an Architect's Heuristic (a "rule of thumb") based on the Pareto Principle.

In the world of LLM implementation, the "engineering" part of prompt engineering is often split into two very different categories:

1. The 80%: Cognitive Intent & Guardrails

Most LLM failures don't happen because the Python code was wrong; they happen because the intent was ambiguous. When you use a framework like the Trinity (Task, Context, Constraint) during the Business Analysis phase, you are effectively solving:

Scope Creep: Defining exactly what the agent shouldn't do.
Context Poisoning: Filtering out irrelevant data before it hits the prompt.
Outcome Definition: Deciding what "done" looks like (JSON schema, tone, etc.).

If a BA or Architect provides a ticket that already defines these three pillars, they have done the heavy lifting. The developer isn't guessing what the "persona" should be or what the edge cases are—it's already on the page.

2. The 20%: Technical Refinement & Plumbing

The remaining effort is what happens once the "Contract" (the Spec) hits the IDE. This is where the developer focuses on:

Token Optimization: Trimming the BA's prose to save money and latency.
Model Selection: Deciding if this needs a "Large" model or if a "Flash" model can handle it.
Hyperparameter Tuning: Tweaking temperature, top_p, and frequency penalties.
Integration: Writing the actual code (JS/Node, Python, etc.) to pipe the data from the source to the LLM.

The Architect’s Reality: > If you hand a developer a ticket that says "Make an AI that helps with insurance," they spend 100% of their time playing "Guess the Requirement." If you hand them a Trinity Spec, they spend 20% of their time on the prompt and 80% on building a robust, production-ready integration.

In short: The "80%" to represent the Foundational Clarity that a solid BA process provides. Without it, the developer is just a prompt-guesser, not an engineer.

Beyond the Chatbox: Engineering Your Prompts

Luis Cruz — Sat, 07 Feb 2026 04:50:21 +0000

Introduction

We’ve all been there: you ask an AI for a specific piece of code or a strategic breakdown, and it responds with a polite but slightly off-target "wall of text." For developers building AI agents, "conversational" prompting is quickly becoming a bottleneck. It’s too vague for logic and too disorganized for complex workflows.

To build reliable systems, we need to stop chatting with AI and start architecting our instructions.

In this post, we’re breaking down the three distinct prompting styles that transform the way you interact with LLMs:

The Narrative Style: Using intent-driven user stories to trigger the AI’s anticipatory intelligence.

The Workflow Style: Defining step-by-step operational manuals for flawless execution.

The Logic Style: Implementing strict Given-When-Then constraints to handle edge cases and data validation.

Whether you're managing complex APIs or architecting database migrations, mastering these three styles is the difference between a "helpful toy" and a production-ready agent. Let’s dive into it.

Why write this post?

This post is designed to help you transition from "prompting by feeling" to "prompting by design." By categorizing your instructions into Narrative, Workflow, and Logic styles, you can match the structure of your prompt to the complexity of the task.

1. Narrative Style: The Visionary

Focus: Alignment, Intent, and Anticipation.

The Narrative style uses the "User Story" framework to give the AI a high-level perspective. It treats the AI as a consultant who helps to discover the best route. It’s most effective when you want the AI to use its "internal world model" to fill in gaps you might have missed.

Best For: Brainstorming, initial drafts, strategic planning, and creative problem-solving.
Implementation Tip: Spend the most time on the "So That" clause. This is the "Intelligence Trigger" that tells the AI which direction to lean.

Sample: API Design

"As a Lead Backend Engineer, I want to design a RESTful API for a high-traffic e-commerce cart, so that the system remains performant under load and handles partial failures gracefully."

🛠️ Template: Narrative Style

# ROLE
As a [Insert Persona/Role/Title],

# INTENT
I want to [Insert specific task or output],

# CONTEXT/GOAL
So that [Insert the ultimate 'Why' and the desired value].

2. Workflow Style: The Architect

Focus: Sequence, Process, and Result.

The Workflow style treats the AI as an operator following a manual. It moves the conversation from "what" to "how," ensuring the agent follows a specific sequence of thoughts or actions.

Best For: Multi-step coding tasks, document processing, and repeatable agentic behaviors.
Implementation Tip: Use "Post-conditions" to define the "Success State." This prevents the AI from finishing with a half-baked response.

Sample: Code Review Agent

Actor: Senior Security Researcher.
Goal: Identify potential SQL injection and XSS vulnerabilities in the provided PR.
Main Flow:

Scan the input code for any unsanitized user inputs.

Trace those inputs to database queries or DOM manipulation points.

Categorize risks as Low, Medium, or High.

Post-Conditions: Output must be a Markdown table summarizing the risks and suggesting specific remediation code.

🛠️ Template: Workflow Style

## [AGENT ROLE]
**Actor:** [Define the persona]

## [OBJECTIVE]
**Goal:** [Describe the final result]

## [PROCESS]
**Main Flow:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

## [SUCCESS CRITERIA]
**Post-conditions:** [Specify formatting, tone, or delivery requirements]

3. Logic Style: The Compiler

Focus: Precision, Constraints, and Edge Cases.

The Logic style (Given-When-Then) is for high-stakes precision. It treats the prompt like a unit test, ensuring that specific conditions always trigger specific results. It leaves almost zero room for AI "creativity."

Best For: Data transformation (JSON/CSV), enforcing strict guardrails, and handling complex business rules.
Implementation Tip: Use this when "close enough" isn't good enough. It is excellent for "Self-Correction" loops.

Sample: Data Transformation

Scenario: User Input Validation

Given: A raw string containing a date and a user name.

When: The date format is not ISO-8601.

Then: Convert the date to YYYY-MM-DD and wrap the output in a JSON object with a warning key.

🛠️ Template: Logic Style

### SCENARIO: [Title of specific condition]
* **Given:** [The state of the input or the specific context]
* **When:** [The trigger or action that occurs]
* **Then:** [The exact, non-negotiable output or behavior]

---
(Repeat for multiple scenarios)

Implementation Guidance: The "Trinity" Matrix

If the task is...	Use this Style	Because...
Vague or Open-ended	Narrative	You need the AI to provide expertise you might lack.
A specific procedure	Workflow	You need the AI to follow a proven, reliable method.
Rule-heavy or Technical	Logic	You need the AI to act as a logic gate, not a writer.

Summary: Choosing Your Weapon

The secret to high-performing agents isn't finding the "perfect" model; it's choosing the right structure for the task at hand. By moving away from colloquial "vibes" and adopting a technical framework, you reduce hallucinations and increase reliability.

The Trinity at a Glance
Narrative Style: Use when you need a partner. It aligns the AI with your "Why," allowing it to anticipate your needs through the "So That" clause.

Workflow Style: Use when you need a builder. It provides a rigid sequence of operations that ensures nothing is skipped in complex, multi-step tasks.

Logic Style: Use when you need a gatekeeper. It applies strict Given-When-Then rules to handle high-stakes edge cases where precision is non-negotiable.

The Developer's Edge
In the world of AI-assisted development, your prompts are your code. A sloppy prompt is just technical debt waiting to happen. By using the Trinity, you aren't just asking for help—you're architecting a solution.