Narrative Development Protocol: A Practical Compass for AI-Native Software Builders

AI-native development often starts with direct commands instead of declared intent. A developer opens an AI tool and begins issuing build instructions: create this endpoint, generate that schema, add this feature, refactor that module. The system grows quickly, but the AI is optimizing for each local request, not for a clearly stated overall goal. It is doing exactly what it is asked to do, which is also the problem. Without an explicit narrative of purpose and constraints, the output converges toward prompt satisfaction, not product intent.

In many of these projects, the real objective and reasoning are not written down in a structured way at all. They exist as mental context in the developer’s head. The AI does not see that context. It sees only the latest instruction. As a result, it produces plausible fragments that fit the moment but not necessarily the direction. The code can be clean and functional while still being misaligned with the actual target, because the target was never formalized as an artifact the AI could work against.

The Narrative Development Protocol, or NDP, is a narrative-first software development paradigm designed to correct that starting condition. Its core principle is direct: a product should exist as a narrative before it exists as a codebase. The narrative defines what the system is for, how key terms are used, and what outcomes are expected. Implementation is then guided by that narrative instead of by a stream of isolated prompts.

NDP is a protocol, not a methodology, framework, or tool. It does not prescribe ceremonies or delivery models. It defines a small, strict set of narrative artifacts that anchor intent and language so both humans and AI systems can work against the same reference. Instead of prompting the AI with only tasks, developers provide bounded stories derived from an explicit narrative source.

The working loop is structured but lightweight. Narrative artifacts are authored first and refined until ambiguity is visible. Open questions and decisions are recorded instead of guessed. Implementation is treated as an interpretation of a single story at a time. Results are reviewed, and feedback can update either the code or the narrative. The narrative remains the controlling layer, not an afterthought.

AI operates under constraint in this model. It is used as a translator from narrative stories to technical proposals. When meaning is unclear, it is expected to ask questions. Its outputs are proposals, not authoritative answers, and human review is required before acceptance. This preserves velocity while preventing silent goal drift driven by underspecified prompts.

The sections that follow present NDP as a practical guideline for developers who want to work fluidly with AI tools without losing directional control. You will see how to structure narrative artifacts, how to hand stories to AI for implementation, and how to run alignment checks between narrative and code, with concrete examples built around onboarding and payment flows.

, -

Principles and Scope

Scope

This guide targets AI-native development teams who build software in continuous collaboration with AI systems. It assumes that natural language specifications and AI-assisted implementation are part of the normal workflow. The purpose here is not to teach project management or delivery practice, but to define a protocol for keeping product intent explicit and operational while working with AI.

NDP defines how intent is expressed and used as a controlling reference during development. It focuses on narrative artifacts and their relationship to implementation. Team structure, planning style, and delivery process remain outside its scope.

What NDP is and is not

NDP is a narrative-first development protocol. It standardizes how product intent is written, maintained, and interpreted across humans and AI tools. It establishes a minimal, fixed set of authoritative narrative artifacts and rules for how they evolve alongside the system.

NDP does not define planning cycles, estimation models, prioritization schemes, architecture styles, or management practices. It does not automate engineering judgment and does not authorize autonomous system decisions. It introduces constraints on how intent must be recorded and referenced, not how teams must organize.

The core principle

A product should exist as a narrative before it exists as a codebase.

Intent, constraints, exclusions, and trade-offs are written explicitly before they are embedded into structures and interfaces. Technical decisions are not delayed, but they are evaluated against a declared purpose rather than local convenience. The narrative is treated as a testable reference for why the system behaves the way it does.

The mental model

NDP treats narrative artifacts as first-class, source-controlled inputs to development. They are not supporting documentation but controlling specifications in natural language form.

Development proceeds as a repeating loop:

• Narrative intent is refined
• Gaps and ambiguities are surfaced
• Clarifications are recorded
• Implementation is produced as a bounded interpretation
• Observed behavior and review results feed back into narrative updates

The narrative drives the process. The code remains provisional.

, -

Core artifacts

An NDP project is anchored by a compact, stable set of narrative artifacts. These artifacts are not auxiliary documentation. They function as authoritative product definitions expressed in structured natural language and are intended to be directly usable by both developers and AI systems. Their purpose is to keep intent precise, inspectable, and operational throughout development.

Manifest

The Manifest defines what the product is meant to achieve and the boundaries within which it operates. It is outcome-oriented and avoids implementation detail. It states the intended result, the primary actor or beneficiary, measurable success criteria, included capability areas, explicit exclusions, and relevant operating constraints.

The Manifest must remain concise and readable in full. If it cannot be expressed clearly and briefly, the product definition is considered incomplete. Explicit non-goals are required to establish boundaries and prevent later reinterpretation of scope.

Vocabulary

The Vocabulary establishes controlled domain language. It removes ambiguity from key terms that appear in narrative artifacts and implementation discussions. Each entry specifies the accepted meaning of a term, excluded meanings, and notes on ambiguity, overloaded usage, or legacy interpretations where relevant.

Vocabulary control is treated as a defect-prevention mechanism. Divergent term usage leads to divergent implementations. Aligning language reduces hidden semantic drift across stories and code.

Stories

Stories are the atomic behavioral specifications of the system. Each story defines one bounded unit of expected behavior in narrative form. Stories are not tasks or backlog items. They are precise intent statements that can be interpreted into implementation and verified against outcomes.

Each story carries a stable identifier and describes expected outcomes, participating actors, inputs and outputs, preconditions, constraints, error behavior, and observability signals. If uncertainty exists, it is recorded explicitly rather than resolved by assumption. Stories are required to remain atomic so they can be implemented, reviewed, and validated without hidden dependencies.

Supporting registers

In addition to primary artifacts, NDP maintains structured registers that record how intent interacts with uncertainty and trade-offs during development. These registers externalize risk, reasoning, and unresolved areas so they can be referenced and reviewed.

• Assumptions record unverified but relied-upon statements. Each assumption must be explicit, testable in principle, and referenced by dependent stories. Assumptions are treated as risk declarations, not background context.
• Decisions record resolved trade-offs. Each decision captures the situation, rejected alternatives, chosen direction, and expected consequences. Only choices that constrain future options qualify. This prevents repeated re-evaluation of previously settled questions.
• Open questions track unresolved issues that affect correctness, scope, or behavior. Each question includes an owner, relevance, and a defined condition that triggers resolution. Open questions are acceptable; untracked uncertainty is not.

, -

Minimal Schemas and Templates

Minimal artifact schemas

NDP artifacts use a defined minimum structure so they can be reviewed consistently and interpreted reliably by both humans and AI systems. These schemas represent the required baseline only. Teams may extend them with additional fields where useful, but required fields should not be removed. Structural consistency is more important than formatting style.

Schemas exist to standardize completeness, not to increase ceremony. If a required field cannot be filled without guessing, the artifact is incomplete and should return to clarification.

Required fields by artifact type

• Manifest: ID, intent, primary actor, success criteria, in-scope capabilities, explicit non-goals, operating constraints.
• Vocabulary entry: term, definition, non-definition, notes.
• Story: ID, outcome-oriented intent, actors, inputs, outputs, preconditions, constraints, error cases, observability expectations, open questions (explicitly marked).
• Assumption: ID, statement, falsification method, dependent stories.
• Decision: ID, context, alternatives rejected, rationale, consequences.
• Open question: ID, question, owner, reason it matters, trigger for resolution.

Canonical templates

Each project should maintain one canonical template set for all artifact types. Templates serve as the reference structure for new entries and updates. Duplicate or competing templates should be avoided, as template drift leads to schema drift and reduces interpretability for both reviewers and AI systems.

, -

Workflow and Controls

Work admission

Under NDP, implementation work is admitted only through approved stories. Every code change must be traceable to a specific story artifact. If a proposed change cannot be mapped to an existing story, it must either be formalized as a new story or declined as out of scope. This constraint ensures that implementation remains anchored to declared behavioral intent rather than opportunistic modification.

Stories are controlled artifacts and may evolve, but only through explicit narrative revision. Behavioral change is introduced by updating the story first, then aligning implementation. Silent divergence at code level is treated as a protocol violation.

Narrative change controls

Narrative artifacts are mutable but governed. Each story modification requires a short reason statement describing what changed and why. Changes that alter intent or scope must reference a corresponding Decision record. When a narrative revision invalidates previously accepted behavior, the affected story is marked for revalidation before further dependent work proceeds.

Where dual formats exist for human-oriented and AI-oriented specifications, they are updated together. Parallel but inconsistent representations are not permitted.

Regular alignment checks are mandatory. On a defined cadence, such as daily in solo workflows or after merges in team environments, code and narrative artifacts are compared and a structured gap analysis report is produced. Findings are reviewed and resolved explicitly rather than ignored.

Traceability

Traceability is enforced across artifacts and implementation:

• Code changes, commits, and pull requests reference the relevant story identifier.
• Stories maintain references to implementing modules or services.
• Tests and observability signals are linked to story identifiers.

This creates a bidirectional map between narrative intent and executable behavior.

Verification mapping

Each story defines at least one observable outcome signal that indicates correct behavior. At least one automated test or defined manual verification step must map to that signal. When verification fails, the outcome is recorded as narrative tension requiring review, not patched silently in code. Verification assets are introduced as soon as a story reaches a runnable slice and are executed continuously thereafter.

Technology baseline control

Primary technology choices, such as runtime, language, and core framework, are established early and treated as controlled constraints. Changes to these foundations require a recorded Decision entry with rationale and consequences. This prevents uncontrolled platform drift driven by local optimization.

Narrative deprecation

Narrative artifacts may be formally deprecated when no longer valid. Stories, vocabulary terms, or declared capabilities can be marked obsolete with a reason and, where applicable, a replacement reference. Deprecated items no longer admit new implementation work and remain only for historical traceability.

Manual validation step

Before delegating implementation primarily to AI-assisted workflows, at least one story is implemented manually end to end. This serves as a validation of narrative clarity and completeness. If repeated interpretation is required during manual implementation, the narrative artifact is revised. Early correction at the narrative level is considered lower cost than structural correction after broader implementation.

, -

AI and Governance

AI-assisted development model

NDP permits AI-assisted implementation under defined governance constraints. AI systems operate as bounded translators from narrative artifacts to technical proposals. They are not treated as authors of intent, scope, or domain meaning. Human review remains a required control point. Where human review is absent or purely symbolic, the protocol is not being followed.

Fully autonomous coding agents that select goals, expand scope, or chain uncontrolled tasks are outside recommended practice. AI participation is scoped, supervised, and artifact-driven.

AI specification inputs

Narrative artifacts are the canonical input to AI-assisted work. For each human-readable specification artifact, a structurally equivalent machine-oriented specification file may be maintained, typically in .ai.yaml form. Paired artifacts share identifiers and intent and are kept synchronized through an explicit update procedure defined in a project-level AI instructions document.

Synchronization is treated as a control requirement. Divergent human and AI specifications are considered invalid until reconciled.

Agent operating constraints

When an AI agent is used for implementation, it is constrained to a single approved story at a time. Narrative artifacts provide the only authoritative requirement source. Missing information must result in clarification questions rather than inferred detail. Generated output is classified as a proposal and requires acceptance review before integration.

Implementations are expected to remain modular, with explicit inputs and outputs. Sensitive or regulated data is excluded from prompts and replaced with redacted or synthetic equivalents.

AI is most effective when applied to well-specified stories, consistency checks across artifacts, and detection of missing constraints or unhandled error paths.

Operational controls

• Alignment and gap analyses may be scoped to the active story or recently modified components in larger systems.
• Report structure is adaptable to domain risk and project scale, provided discrepancies are made explicit and reviewable.
• Human review may be lightweight but must be recorded as an explicit approval or rejection outcome tied to the story or change set.

AI systems are not permitted to introduce new requirements, extend scope, define new domain concepts, or override narrative intent. When AI output exposes a mismatch between behavior and narrative, the narrative artifact is corrected first, followed by implementation updates.

Narrative governance roles

NDP assigns governance responsibilities without prescribing org charts:

• Narrative stewardship maintains cross-artifact coherence and language consistency.
• Decision authority approves intent or scope changes.
• Story acceptance authority confirms that stories are sufficiently defined for implementation.
• Prompt and agent-instruction authority controls the rules under which AI systems operate in AI-heavy workflows.

Narrative lint practice

A lightweight, repeatable review discipline is applied before and after implementation. Before work begins, artifacts are checked for outcome-oriented intent, vocabulary consistency, explicit constraints, defined failure behavior, and observable outcomes. After implementation, reviewers verify alignment with the story, detect implicitly introduced constraints, and reassess dependent assumptions. The practice is brief and systematic rather than procedural overhead.

Narrative tension handling

Conflicts between expected and observed behavior are recorded as narrative tension signals. Typical triggers include invalidated assumptions, weakened decisions, newly discovered constraints, or execution results that contradict a story. Resolution occurs by revising narrative artifacts first, then adjusting code accordingly. Silent correction at code level without narrative update is disallowed.

Narrative partitioning

When scope, actor models, or domain boundaries diverge significantly, artifacts are partitioned into separate manifests. Vocabularies may inherit from or fork existing sets with explicit mapping rules. Cross-manifest story dependencies are declared through direct references rather than implicit linkage.

Tooling compatibility contract

NDP defines minimal tooling expectations:

• Artifacts are stored in plain text or structured, diff-friendly formats within a versioned repository.
• A consistent directory layout groups core artifacts, stories, registers, and AI instruction files.
• A canonical identifier scheme is applied across artifact types to preserve traceability and cross-reference stability.
• No specific platform or editor is required, and CLI-oriented workflows are preferred for auditability and change control.

Canonical identifier format (default)

Default identifier patterns follow a typed prefix and area code with numeric sequence, for example:

• M-AREA-### for manifests
• S-AREA-### for stories
• A-AREA-### for assumptions
• D-AREA-### for decisions
• Q-AREA-### for open questions

, -

Adoption and Failure Modes

Adoption patterns

NDP is designed for incremental adoption. Teams apply the smallest viable subset of the protocol that resolves their current coordination or intent-control problems. Full protocol coverage is not required at the outset. Artifact discipline is expanded only where risk or ambiguity justifies it.

A minimal adoption footprint consists of a Manifest, a controlled Vocabulary, and a bounded set of Stories that define intended behavior. This level establishes a stable intent baseline and shared language without introducing additional control layers.

Expanded adoption typically adds formal work admission controls, lightweight narrative lint reviews, and structured registers for assumptions and decisions. These additions improve traceability and reduce hidden reasoning and risk.

AI-intensive environments benefit from additional safeguards, including explicit agent instruction documents, strict single-story execution boundaries, and mandatory ambiguity escalation through questions rather than inference. These controls reduce prompt-driven drift and unintended scope expansion.

Protocol growth is additive. Controls are layered in response to observed failure patterns rather than introduced by preset maturity stages.

Common failure modes and anti-patterns

Several recurring anti-patterns indicate protocol breakdown:

• Treating stories as task tickets rather than behavioral intent definitions
• Letting vocabulary diverge between artifacts and code
• Allowing AI systems to silently fill specification gaps instead of surfacing questions
• Allowing implementation to become the de facto specification
• Replacing structured artifacts with informal prose
• Expanding stories beyond atomic behavioral scope
• Redefining terminology implicitly through usage rather than controlled vocabulary updates
• Allowing AI-generated output to introduce new requirements or domain concepts
• Editing narrative artifacts after implementation to justify existing behavior instead of guiding it
• Expanding manifest scope without corresponding decision records or non-goal revisions

Corrective action typically reduces scope and restores artifact clarity rather than adding additional procedural layers.

Non-target use cases

NDP is not intended for every type of work. It is generally unnecessary for:

• Disposable scripts
• Solo exploratory spikes
• Research prototypes
• Tightly time-boxed experiments

In such cases, protocol overhead exceeds benefit.

Compliance quick check

A lightweight compliance check can be performed at any time:

• The Manifest is readable end to end without fragmentation.
• Domain-critical terms appear in the Vocabulary with controlled definitions.
• Active Stories include defined inputs, constraints, and observable outcomes.
• Implementation changes are traceable to Story identifiers.
• Open Questions have assigned ownership and resolution triggers.
• Deprecated Stories or artifacts are excluded from new implementation work.

Failure on these checks indicates protocol drift and triggers artifact correction rather than process expansion.

, -

Relationship and Closing

Usage validation

Protocol adherence can be evaluated with a single diagnostic question: can a developer or AI agent determine the system’s intended behavior, explicit boundaries, and governing rationale directly from the narrative artifacts, without inspecting the codebase? If this is possible, NDP is functioning as designed. If understanding depends primarily on reading implementation, narrative artifacts have degraded into secondary documentation and no longer serve as controlling specifications.

This check is outcome-based rather than procedural. It does not measure how many artifacts exist, but whether they are sufficient to convey operational intent independently of code.

Relationship to Narrative Management Protocol (NMP)

NDP operates at the development layer and is compatible with broader narrative governance models such as the Narrative Management Protocol (NMP). The two protocols address different control surfaces.

NDP defines how intent is structured, refined, and translated into implementation through narrative artifacts and constrained interpretation. NMP defines how intent is governed across the lifecycle through versioning, review, and change authority structures. One focuses on operationalization in day-to-day building activity, the other on cross-project or cross-phase intent governance.

NMP is not required for NDP adoption and remains out of scope for this guide. NDP remains self-sufficient as a development protocol, particularly in AI-native workflows.

Closing

NDP treats intent as an operational asset rather than background context. Its purpose is to keep purpose, constraints, and boundaries explicit and inspectable as systems evolve. The protocol relies on structured narrative artifacts, controlled interpretation, and explicit review rather than tooling mandates.

Tools may vary and automation levels may change, but narrative control requirements remain constant. Where narrative artifacts lead and implementation follows under constraint, system behavior remains explainable and change remains deliberate.

, -

Example Domain: User Onboarding

This example illustrates NDP artifacts applied to a SaaS onboarding flow for a team collaboration product. The goal is to show how intent, language, behavior, and governance records are expressed in structured narrative form and prepared for AI-assisted interpretation. The example is intentionally compact but complete enough to support implementation work.

Manifest

• ID: M-ONB-001
• Intent: Enable newly registered teams to reach first successful collaboration within 30 minutes of signup.
• Primary actor: Team admin (account owner)
• Success criteria: At least 70 percent of new signups create a workspace and invite at least one teammate within 24 hours.
• In-scope capabilities: Workspace creation, onboarding checklist presentation, teammate invitation, first project creation.
• Explicit non-goals: Sales qualification flows, training media libraries, competitive data import.
• Operating constraints: Onboarding guidance must not block access to core features; checklist completion remains optional.

Vocabulary entries

Workspace

• Definition: A shared container where a team organizes members and projects.
• Non-definition: Not an individual user account and not a single project entity.
• Notes: Current product version supports one workspace per team.

Activation

• Definition: The state reached when a workspace exists and at least one additional teammate has joined.
• Non-definition: Not mere account registration.
• Notes: Used strictly for measurement and success evaluation.

Checklist item

• Definition: A single onboarding step with a defined completion signal.
• Non-definition: Not a documentation page or passive help content.
• Notes: Items are advisory and non-blocking.

Stories

S-ONB-WORKSPACE-001

• Intent: Permit a team admin to create a workspace after account registration.
• Actors: Team admin
• Inputs: Workspace name
• Outputs: Workspace record created, admin assigned owner role
• Preconditions: Account exists and verification requirements are satisfied
• Constraints: Workspace name must be unique within the account scope
• Error cases: Duplicate name, invalid format
• Observability expectations: workspace_created event count
• Open questions: Whether creation is allowed prior to email verification

S-ONB-CHECKLIST-001

• Intent: Display an onboarding checklist with dynamic progress indicators.
• Actors: Team admin
• Inputs: Current workspace state
• Outputs: Checklist view with per-item completion status
• Preconditions: Workspace exists
• Constraints: Checklist remains optional and non-blocking
• Error cases: Checklist configuration unavailable
• Observability expectations: checklist_viewed and checklist_item_completed events
• Open questions: Final item set for initial release

S-ONB-INVITE-001

• Intent: Allow a team admin to invite a teammate via email.
• Actors: Team admin, invitee, email service
• Inputs: Invitee email address
• Outputs: Invitation dispatched, pending invite stored
• Preconditions: Workspace exists
• Constraints: Maximum of ten invites per hour per workspace
• Error cases: Email delivery failure, invalid address format
• Observability expectations: invite_sent and invite_accepted events
• Open questions: Whether existing-account invitees are auto-linked

Assumptions

• ID: A-ONB-EMAIL-001
• Statement: Email delivery success rate meets or exceeds 95 percent.
• Falsification method: Weekly delivery metrics below threshold.
• Dependent stories: S-ONB-INVITE-001

Decisions

• ID: D-ONB-TOUR-001
• Context: Onboarding guidance visibility versus friction.
• Alternatives rejected: Mandatory modal tour, blocking full-screen wizard.
• Rationale: Preserve rapid time-to-value and reduce early abandonment.
• Consequences: Guidance effectiveness depends on voluntary checklist use.

Open questions

• ID: Q-ONB-ACTIVATION-001
• Question: Whether activation should require first project creation in addition to teammate invitation.
• Owner: Product lead
• Reason it matters: Affects success metrics and onboarding sequence design.
• Trigger for resolution: Prior to public beta release.

, -

Example Domain: Payments

This example demonstrates how NDP artifacts describe a subscription billing flow with card-based payments. The focus is on expressing billing intent, boundaries, behavioral rules, and operational risk in structured narrative form so that implementation and AI-assisted translation remain constrained by explicit definitions rather than inferred practice.

Manifest

• ID: M-PAY-001
• Intent: Enable customers to initiate and maintain a paid subscription with predictable billing behavior and explicit failure handling.
• Primary actor: Account owner
• Success criteria: At least 90 percent of trials convert to paid within seven days; failed payment situations reach resolution within 72 hours.
• In-scope capabilities: Payment method registration, subscription start, monthly renewal, failed payment handling, subscription cancellation.
• Explicit non-goals: Enterprise invoice workflows, multi-currency settlement, offline payment channels.
• Operating constraints: PCI exposure minimized through tokenization; the payment provider is authoritative for charge status.

Vocabulary entries

Payment method

• Definition: A provider-issued token representing a stored card credential.
• Non-definition: Not raw card numbers or bank transfer instructions.
• Notes: Token lifecycle and storage are provider-managed.

Subscription state

• Definition: The billing lifecycle status of a subscription, such as trial, active, past_due, or canceled.
• Non-definition: Not equivalent to product access state.
• Notes: Access policy is derived separately from billing state.

Dunning

• Definition: Automated retry and customer notification sequence following a failed charge.
• Non-definition: Not manual collections activity or immediate access revocation.
• Notes: Timing and retry limits are policy-driven.

Stories

S-PAY-METHOD-001

• Intent: Permit an account owner to register a payment method.
• Actors: Account owner, payment provider
• Inputs: Card details submitted through provider flow
• Outputs: Payment method token stored for billing use
• Preconditions: Account exists
• Constraints: Platform does not store raw card data
• Error cases: Provider unavailable, card declined
• Observability expectations: payment_method_added and payment_method_failed events
• Open questions: Whether multiple payment methods are supported per account

S-PAY-SUBSCRIBE-001

• Intent: Start a paid subscription after a valid payment method is available.
• Actors: Account owner, payment provider
• Inputs: Selected subscription plan
• Outputs: Subscription created, initial charge attempted
• Preconditions: Payment method token exists
• Constraints: Charge operations are idempotent
• Error cases: Initial charge failure, unavailable plan
• Observability expectations: subscription_started, charge_succeeded, and charge_failed events
• Open questions: Whether authorization-only charges allow provisional activation

S-PAY-RENEW-001

• Intent: Execute monthly subscription renewal billing.
• Actors: System, payment provider
• Inputs: Billing cycle trigger
• Outputs: Renewal charge attempt and updated subscription state
• Preconditions: Subscription is active
• Constraints: Retry behavior follows defined dunning policy
• Error cases: Charge failure, provider timeout
• Observability expectations: renewal_attempted and renewal_failed events
• Open questions: Retry count threshold before transition to past_due

S-PAY-DUNNING-001

• Intent: Manage retries and notifications after failed charges.
• Actors: System, account owner, notification service
• Inputs: Failed charge signal
• Outputs: Customer notification and scheduled retry attempts
• Preconditions: Charge failure recorded
• Constraints: Maximum of four retries within seven days
• Error cases: Notification delivery failure
• Observability expectations: dunning_started and dunning_resolved events
• Open questions: Whether in-application alerts supplement email notices

S-PAY-CANCEL-001

• Intent: Allow an account owner to cancel an active subscription.
• Actors: Account owner
• Inputs: Cancellation request
• Outputs: Subscription marked for cancellation at period end
• Preconditions: Subscription is active or past_due
• Constraints: Cancellation does not trigger automatic refunds
• Error cases: Provider update failure
• Observability expectations: subscription_canceled events
• Open questions: Whether a pause option is offered as an alternative

Assumptions

• ID: A-PAY-PROVIDER-001
• Statement: Payment provider availability meets or exceeds 99.9 percent uptime.
• Falsification method: Monthly provider reports below threshold.
• Dependent stories: S-PAY-METHOD-001, S-PAY-SUBSCRIBE-001, S-PAY-RENEW-001

Decisions

• ID: D-PAY-RETRY-001
• Context: Strategy for handling failed charges.
• Alternatives rejected: Manual-only recovery, immediate cancellation on first failure.
• Rationale: Reduce churn while limiting operational overhead.
• Consequences: Recovery depends on reliable automated notification.

Open questions

• ID: Q-PAY-ACCESS-001
• Question: Which access policy applies while a subscription is in past_due state.
• Owner: Product lead
• Reason it matters: Directly affects user experience and support load.
• Trigger for resolution: Prior to billing feature beta release.

, -

Example AI Instructions

Purpose

This instruction set defines how AI systems are permitted to participate in NDP-governed development. It establishes operating constraints, synchronization duties, and review controls so AI-assisted work remains aligned with narrative artifacts and traceable intent.

Primary inputs

AI agents operate from machine-oriented narrative specifications, typically maintained as .ai.yaml artifacts. These files serve as the primary executable narrative input for agents. Human-readable narrative artifacts remain the authoritative reference for human interpretation and approval. Both representations are required to remain consistent at all times.

Specification synchronization controls

Human-readable and machine-oriented specifications are maintained as paired artifacts. Any modification to one requires a corresponding update to the other within the same change set. Partial updates are not accepted.

If inconsistencies are detected between paired specifications, AI execution must pause and request clarification. Agents are not permitted to resolve cross-spec conflicts through inference.

Stable identifiers, declared non-goals, and scope boundaries are preserved unless a recorded Decision artifact authorizes change. Missing requirements are not inferred. They are surfaced as clarification questions or recorded as open questions.

Review control

AI-generated output is classified as a proposal artifact. Human review and explicit acceptance are required before implementation or merge. Unreviewed AI output is not considered protocol-compliant. Fully autonomous agent execution without recorded approval gates is excluded from recommended use.

Alignment control

On a defined operational cadence, such as daily in solo workflows or after integration events in team settings, agents perform a code-to-spec comparison and produce a structured gap analysis artifact in .ai.yaml form. Findings are reported for explicit disposition rather than auto-corrected.

Scope control

Agent activity is limited to the referenced story artifact. Scope expansion, implicit requirement creation, and introduction of new domain terminology are not permitted without corresponding narrative artifact updates. Vocabulary changes require explicit artifact revision before use.

Modularity and testing controls

AI-generated implementations are structured as self-contained units with explicit interfaces to support parallel work and bounded review. Test definitions are introduced as soon as a story reaches executable form and are executed continuously thereafter. Test absence is treated as incomplete delivery rather than deferred quality work.

Example .ai.yaml instruction artifact

id: AI-INSTRUCTIONS-001

purpose: “Govern AI participation under Narrative Development Protocol constraints.”

primary_inputs:

- “Use .ai.yaml narrative artifacts as primary machine-readable intent sources.”

- “Maintain consistency with paired human-readable artifacts.”

spec_sync_controls:

- “Update paired human-readable and .ai.yaml artifacts together.”

- “Pause and request clarification on any cross-spec conflict.”

- “Preserve IDs and declared non-goals unless a Decision artifact authorizes change.”

- “Do not infer missing requirements; raise questions instead.”

review_control:

- “Treat all generated output as proposal-only until human approval is recorded.”

alignment_control:

- “Produce periodic code-versus-spec gap analysis artifacts.”

- “Report discrepancies for explicit resolution.”

scope_control:

- “Limit work to the referenced story artifact.”

- “Do not introduce new scope or domain terms without artifact updates.”

modularity_control:

- “Generate self-contained units with explicit inputs and outputs.”

testing_control:

- “Attach tests once a runnable slice exists and execute continuously.”

Final Word

The Narrative Development Protocol is intentionally minimal and constraint-oriented. It is not meant to be adopted verbatim or enforced mechanically. Treat the structures, schemas, and controls in this guide as a starting point, not a fixed doctrine. Teams are expected to adapt field sets, review cadence, artifact depth, and AI guardrails to their domain, risk profile, and delivery style.

Selective adoption is valid. Critical adjustment is encouraged. You are expected to challenge the shapes, refine the templates, and remove or extend elements where your context demands it. What should remain intact is the underlying discipline: make intent explicit, keep scope bounded, surface ambiguity instead of masking it, and preserve the constraint that narrative leads and implementation follows. If those constraints hold, the protocol is functioning, even if your local form differs.

This paradigm is in development, and it can only be improved by working on it together, as humans.

About the Author

My name is Ramazan Yavuz and i am software developer with over ten years of professional development experience, working across full stack systems, infrastructure, and AI-assisted engineering workflows. My recent work focuses on AI-native development practices in regulated and compliance-sensitive environments, where traceability, auditability, and intent clarity are operational requirements rather than preferences.

I work on methods and tooling patterns that improve how humans and AI systems interface during software delivery, with emphasis on constraint-driven design, narrative specifications, and verification-friendly workflows. My projects span regulated data processing, compliance tooling, and AI-supported development systems, with a focus on making high-automation environments more predictable and reviewable.

Originally published on Medium: https://ryavuz.medium.com/narrative-development-protocol-a-practical-compass-for-ai-native-software-builders-6bb9a689e2a1.