Our experiment was to handle a real, week-long task from our backlog using Spec Kit, integrated with AI agents. The results were both promising and revealing. This article shares what worked, what didn’t, and the lessons we learned about using Spec-Driven Development in a mature codebase with years of history.

The Challenge: Why Large Legacy Tasks Are Hard to Execute

Our legacy project is anything but small. With four years of development behind it, the codebase has grown into a complex ecosystem of established patterns, legacy components, and deeply embedded business logic.

The task we selected for the experiment wasn’t algorithmically groundbreaking, but still substantial. It involved creating new components, styling, and API integration. This is the kind of “routine” work that eats up time and represents exactly the type of task where even skilled developers struggle to remember all the nuances.

The Process: How Spec Kit Turned a Jira Ticket into Working Code

Our developer followed a deliberately minimal intervention approach. The goal was to see how much the AI tool could handle autonomously, and where human judgment would still be required.

Step 1: Minimal Context

We gave the agent with integrated Spec Kit the Jira ticket number. Because we had the JIRA MCP (Model Context Protocol) connected, the AI agent could autonomously read and analyze the task details. No hand-holding, no additional explanations.

Step 2: Autonomous Analysis 

The AI tool read the ticket, explored the existing codebase, identified relevant components, and recognized established patterns. It helped map the task to the real project codebase.

Step 3: Planning

Spec Kit generated a detailed specification and implementation plan. This phase delivered an unexpected benefit: the AI surfaced inconsistencies and ambiguities between the ticket requirements and the existing implementation. These issues would have likely been discovered much later, during development or even testing. Here, the AI tool acted as a technical analyst, refining the task before writing the code.

Step 4: Implementation

Following its own plan, the AI agent began generating code. It produced the bulk of the boilerplate code (components, styles, types) strictly adhering to the patterns it had identified in the project.

Step 5: Review and Polish

Our developer shifted into reviewer mode. He inspected the generated code, fixed integration issues with the backend (which proved to be the AI’s weak spot), and performed light refactoring. Notably, the core business logic generated by the AI agent required no modification.

The Results: Faster Delivery with Maintained Code Quality

From the developer’s perspective, the week-long task was completed in roughly half the time it would have taken manually. The time savings came primarily from automating the repetitive, high-volume coding work that’s necessary but doesn’t require deep architectural thinking.

The generated code passed linters and TypeScript checks without issues. More importantly, the AI correctly reused existing components and utilities from the project, rather than reinventing them.

Perhaps the most surprising outcome was the improvement in requirements quality. By surfacing ambiguities and contradictions early, Spec Kit played the role of an analyst, asking clarifying questions at the very beginning of the process, before development began.

Key Spec Kit Limitations in Practice

No tool is perfect, and our experiment revealed important constraints that shaped how we think about Spec Kit’s role:

• Spec Kit is overkill for tasks estimated at two days or less. The overhead of going through the specification and planning phases exceeded the time savings from automation. For smaller tasks, working directly with an AI agent makes more sense;

• Integration remains the weak link, especially with external APIs and complex edge cases. Code involving external APIs and complex integration logic often required manual adjustment. The AI excelled at generating code within the boundaries of the existing system, but struggled with connections to the outside world;

• Better input produces better output. The quality of results correlated directly with the quality of the input. Tasks like “make it look like the screenshot” were doomed from the start. We learned that detailed text descriptions, clear acceptance criteria, components used, and links to related Jira tickets provide Spec Kit with the necessary context to understand the task;

• The reviewer’s expertise matters most. Spec Kit acts as a multiplier that amplifies the capabilities of the person using it. In the hands of a well-versed developer who understands architecture, patterns, and the project’s context, it removes friction and accelerates delivery. However, it also multiplies the errors of junior developers, who wouldn't notice problems in the generated code. A thorough code review by a human becomes just as, if not more, important.

When and How to Use Spec Kit Effectively

Looking back at the experiment, several lessons stand out that could benefit other teams considering similar tools.

Spec Kit works best for large, well-described tasks. The ideal use case is substantial work with significant boilerplate. For instance, new modules, complex features, or anything that would normally require days of writing code and follows established patterns. Here, the speed gains and planning improvements are maximized.

Invest in ticket quality. A critical precondition was the quality of the task description. Over time, we’ve been moving toward making our tickets self-sufficient, meaning they’re detailed enough that any team member, even someone new to the project, can understand exactly what needs to be done. The initial planning phase incurs a higher cost, but the resulting savings during implementation, software testing, and reduced reliance on analysts and QA team significantly outweigh the upfront expense.

The triad for success. Effective use of Spec Kit requires three elements working together: a skilled business analyst who writes detailed requirements, an experienced developer who sets up the task and performs thorough reviews, and the AI tool itself to automate the routine work. Missing any of these compromises the results.

Maintain human oversight. The AI is not a replacement for an experienced developer, and code review becomes more critical. The main purpose of intelligent coding tools is not to remove developers from the process but to free up their time for higher-value activities.

Conclusion: Spec-Driven Development Works Great in Legacy Projects (with Conditions)

Spec Kit and SDD are most effective in large legacy projects when the specification is clear, the architecture is understood, and human review stays in the loop. AI is not a replacement for developer expertise. It’s a new tool in the engineering toolkit, like version control, linters, or debuggers before it. In the hands of an experienced engineer who understands the architecture, the patterns, and the context, it removes friction and enables faster delivery. For those who don’t yet have that foundation, it can help create messy code faster.

XB Software’s next step is to formalize these learnings into practical guidelines for the team: how to write AI-friendly tickets, when to reach for Spec Kit versus direct agent interaction, and how to maintain quality standards while moving faster. The technology will continue to evolve, but the fundamental principles of clear specifications, thoughtful architecture, and human judgment remain as important as ever.

Then we review the codebase they have. And we take a deep breath.

It’s not the idea that frustrates us. Often, it's market-ready. It's not even the core functionality, which typically performs exactly as demonstrated. Our reaction comes from recognizing what we're about to encounter: hardcoded secrets, database queries that will buckle under load, and a complete absence of error monitoring. It's a pattern that slowly turns into growing regularity.

These founders show us a prototype created through AI-assisted coding that has a domain name and expect it to function as a product. But a compelling demo and a robust product aren't just different stages of the same journey. They represent fundamentally different philosophies of building.

A demo is optimized for a singular moment. It only has to function correctly once, in a controlled environment. A product is engineered for the long haul. Therefore, it must operate reliably tens of thousands of times, without supervision, under unpredictable conditions. This core distinction is the source of nearly every challenge we encounter in such projects.

In this article, we'll walk through the most common issues we discovered when reviewing AI-assisted codebases. More importantly, we’ll consider the real business implications for founders who underestimate the gap between demo and product. So, let's take a look at the risks that threaten your business when you completely entrust your work to AI.

1. No Insight Into Production Health

We ask a client: "Can you walk us through your monitoring and alerting strategy, we do not see them?" The response is often a pause, followed by, "We'll know if something breaks, we don’t need them for now."

Relying on user complaints as your primary alert system looks more like a gamble than a solid business strategy. In a demo environment, you are the sole user and observer. In production, entire features can degrade silently, driving users away without a single notification reaching you.

The Business Impact

Imagine a critical payment integration fails silently. The AI generated code contains an empty catch block, effectively swallowing the error. For weeks, users attempting to check out encounter a frozen screen and simply abandon their carts. The founder, seeing no alerts, is puzzled by a gradual decline in revenue. They only discover the issue when a frustrated customer finally emails to complain. By then, the damage to revenue and user trust is significant, and the root cause remains a mystery. Without proper monitoring, you're flying blind, and your first sign of trouble is often a symptom of a problem that has already cost you dearly.

2. The Missing Staging Environment

This is a common finding: development, staging, and production are all the same server. Every code push, every experimental fix, is deployed directly into the live environment.

The Business Impact

A developer needs to add a simple column to a database table. They connect to what they believe is a test server and run a quick migration script. However, due to a simple typo in the connection details or script itself, the command executes on the production database, dropping a critical table instead of altering it. Months of customer data, transactions, and user records could be erased in milliseconds. While backups might exist, restoring them means significant downtime and potential data loss from the past few hours or days. The trust of users, who suddenly find their accounts or history missing, is incredibly difficult to rebuild. A single deployment mistake can create a business catastrophe.

3. Exposed Credentials in Plain Sight

AI-powered software development tools, optimized for speed and convenience, often embed API keys and secrets directly into the frontend code or client-side requests. This is perfectly acceptable for a local test but catastrophic for a public application.

The Business Impact

Shortly after launch, a curious user or, more likely, an automated bot scanning for vulnerabilities opens the browser's developer tools on the new site. There, in the network traffic, they find a valid API key for a paid service like OpenAI or AWS. Within hours, that key could be sold or used to run thousands of expensive requests. The founders might only realize something is wrong when they receive their next cloud bill, which has ballooned into the tens of thousands of dollars due to unauthorized usage. The frantic scramble to revoke the compromised key, block fraudulent IPs, and secure the application distracts from every other business priority and creates a significant, unexpected financial hit.

4. Unprotected Endpoints and No Rate Limiting

APIs are built to be consumed, but without safeguards, they can be consumed maliciously or accidentally to the point of self-destruction. In web apps built with AI, public endpoints without rate limiting are an open invitation for abuse.

The Business Impact

A startup finally gets its big break, a mention in a major industry newsletter. Excited business owners watch their traffic spike. But within an hour, their website starts loading slowly, then becomes completely unresponsive. Their database, overwhelmed by the sudden influx of requests, has crashed. To make matters worse, their usage-based API bills begin to skyrocket. It turns out one enthusiastic new user wrote a simple script to scrape all the site's data, inadvertently creating a denial-of-service attack. The moment of success becomes a public failure, as potential customers are met with error pages instead of the promised product.

5. The Untested "Stupid User" Scenarios

Models used in AI-driven software development are typically trained on ideal paths. They excel at generating code for a user who fills forms perfectly, clicks once, and has a flawless internet connection. They do not account for edge cases: empty submissions, special characters in file names, or double-clicks.

The Business Impact

A new platform for sharing creative work goes live. Everything works perfectly in testing. Then, a user uploads a file with a name containing an emoji. The file-processing library, chosen by the AI for its speed and simplicity, has no Unicode handling and throws an unhandled exception. The application crashes not just for that single user, but globally because the error isn't isolated. One slightly unconventional filename takes the entire site offline until a developer can manually fix the issue. This scenario illustrates how a single, unexpected user action can create a major incident, turning a "one-in-a-million" edge case into a very real and immediate business disruption.

6. Environment Configuration Sprawl

A single .env file, a shared database connection string, and the same S3 bucket for development and production. The AI configures for functionality, not for safety.

The Business Impact

A developer is running local tests to optimize a slow query. As part of their test, they run a script that truncates a table to reset its data to a known state. Because the application's configuration is shared and points to production, the truncate command doesn't hit the local copy and executes on the live user table instead. In a fraction of a second, critical business data, such as user profiles, orders, settings, can be permanently deleted. This isn't bad coding skills but a failure of structural separation. One wrong command, and the business is facing an operational nightmare with no quick fix.

7. Silent Failures Hidden in Try/Catch Blocks

We see countless try/catch blocks where the catch only logs an error to the console or worse, does nothing at all. The error is caught, the system doesn't crash, but the operation fails silently. The user sees a spinner that never resolves and eventually leaves.

The Business Impact

A founder is perplexed by poor user engagement and low conversion rates. They've invested in marketing, but users seem to bounce from a specific page. What they don't know is that on that page, an API call that fetches critical user data is failing silently for 30% of visitors due to a subtle, unhandled error. The code generated by AI catches the exception, does nothing with it, and returns null. The user sees a blank section or a loading spinner that never stops. They assume the site is broken and leave. Because the error is silent, the founder spends weeks optimizing marketing funnels while the real problem is a technical leak in the product that remains hidden leading to the company continuing to lose potential revenue.

8. No Real-Time Visibility into Costs

The cloud bill arrives, and it's an unwelcome surprise. During early AI-assisted app development, an API may only be called a dozen times. In production, that same API call on every keystroke in a search field scales to thousands of requests per user.

The Business Impact

Using AI coding tools, a founder built a useful search feature for their SaaS product. It works well. However, the AI-generated code fires a database query on every single keystroke, performing an expensive, unindexed full-table scan each time. As the user base grows, so does the database load. The cloud provider's bill, which was a manageable few hundred dollars, suddenly jumps to several thousand. The founder, focused on feature development, never set up cost alerts. They only discover the problem when they see the invoice, realizing that a single, poorly optimized feature is silently destroying their unit economics and profit margins. They are now forced to make an emergency fix while facing the unexpected cost.

9. The Load Test That Never Happened

A prototype built through AI-assisted engineering may handle one user flawlessly. It has never been asked to simulate 50, 100, or 500 concurrent users. The AI did not design for connection pool exhaustion, memory limits, or API throttling.

The Business Impact

A startup has a successful launch day. The press is positive, and users are flooding in. Then, 20 minutes in, the site slows to a crawl and finally stops responding. The database, not configured for a high number of concurrent connections, has reached its limit and is refusing new requests. The server runs out of memory. Users, excited to try the new product, are met with "503 Service Unavailable" errors. The social media mentions quickly turn from praise to frustration. The marketing budget spent on acquiring these users is completely wasted, and worse, the first impression for hundreds of potential loyal customers is one of an unreliable, broken service. The company may never get a second chance with them.

10. The Absence of a Backup and Recovery Plan

There is data on a server, which feels secure until the server is compromised or fails. There are no automated snapshots, no point-in-time recovery configured, and no off-site backups.

The Business Impact

A founder wakes up one morning to find their server has been compromised. A ransomware attack has encrypted their entire database, and a message demands payment for the decryption key. They turn to their team and ask for the latest backup. The answer is worrying: “There is no backup.” The last one was a manual SQL dump taken months ago, stored on a developer's laptop that has since been replaced. All customer data, transaction histories, years of work, everything is gone. The business cannot serve its customers, cannot restore their accounts, and faces operational collapse and potential legal liability for losing sensitive user data. This is an existential threat that could end the company.

What a Successful Transition Looks Like

These issues are not unique. We encounter them in most projects built with AI we're asked to review. The pattern is persistent because the root cause is consistent. AI-assisted software development tools were used to build a demonstration, while the business needs a solid product.

The good news is that these issues are solvable. It requires a deliberate investment in the foundational layer that turns a functioning prototype into a resilient, scalable, and secure business asset. The founders who succeed are those who recognize that an AI-generated codebase is an excellent starting point for a conversation about architecture, not the final architectural blueprint itself. They invest in that foundation before opening the doors to their users.

To solve this, we built a local LLM‑powered agent that runs entirely on our own servers, normalizes chaotic report data, filters out useless noise, enriches descriptions from Jira, and generates a clean list of actual accomplishments. In this article, we break down the architecture and explain why a CPU‑only, on‑premise approach is practical for enterprise clients who prioritize data privacy.

The Problem: Manual Work List Generation Is Slow, Inconsistent, and Insecure

Usually, our managers followed the same routine: collect a month’s worth of developer reports, manually scan through hundreds of entries, and pick out the items that actually represented completed work. This process was straightforward but flawed.

The first issue was data quality. Developers write reports in wildly different formats. Some include detailed Jira ticket IDs and descriptions, others are cryptic one‑liners like “fixed issue”. When a manager who wasn’t deeply involved in the project later reviews these reports, the meaning is often lost. What does “adjusted header” refer to? Which feature did “refactored code” touch? What we really needed was an AI-powered task management approach that could process this unstructured data automatically.

The second issue was duplicate work. Managers would occasionally include tasks that had already been declared in previous months, creating overlaps. Another example is a task that spans several days. In this case, the same activity could be logged repeatedly, producing many near-identical entries. There was no automated way to compare new reports against historical data.

The third issue was security. Initially, we experimented with feeding entire monthly reports into ChatGPT, asking it to clean up the data and suggest a final list. It worked reasonably well, but we were handing over a full month of internal project activity to a cloud service. For many enterprise businesses, especially those in finance or healthcare, that level of exposure is unacceptable.

The Solution: A Secure, On‑Premise AI Agent for Task Extraction from Reports

Our approach was to implement a console‑based application that converts reports into tasks automatically. It runs on our internal server, triggered by a cron job (or an optional API call) at the end of each monthly reporting cycle. The AI agent processes raw reports for each active project, applies a series of transformations, and outputs a polished list of work items.

The entire pipeline runs on a CPU‑only server using Ollama to serve a local instance of the Gemma 4 E2B model. For embedding generation (used in duplicate detection), we use the tiny nomic‑embed‑text model, which is only a few megabytes in size. Here’s a high‑level view of the process flow:

Let’s walk through each stage in detail.

1. Normalization: Making Chaos Readable

A single project might receive 80+ individual reports per month with varying levels of detail. The first task for our AI agent was to normalize these disparate inputs into a consistent, machine‑readable format. This step alone turns a jumble of free‑form text into structured data that the rest of the pipeline can reliably process.

2. Chunking: Working Within Token Limits

This is where we hit our first major technical constraint. Running on CPU via Ollama, our Gemma 4 model is limited to a context window of 4,096 tokens. That’s not a lot. A single month of reports from a busy project can easily exceed that.

We solved this by chunking. The AI system calculates the approximate token count of the combined report text and splits it into batches of about 20 reports each. This ensures that the LLM never runs out of context space and that each chunk receives full attention.

Within each chunk, we also further split entries that contain multiple tasks in a single line (e.g., “Did A, did B, did C”). After this splitting, 22 raw reports became 94 individual work items in one of our test runs.

3. Jira Enrichment: Adding Missing Context

One of the most valuable features of our AI agent is its ability to automatically fetch additional context from Jira. When the system detects a Jira ticket ID in a report, it calls the Jira API to retrieve the ticket description.

Developers often write terse reports assuming the ticket ID is enough. But when that report later appears as “AAA‑123 – done”, it tells nothing. By pulling the full, manager‑written description from Jira, our AI agent replaces the vague entry with a clear, professional summary of what was actually accomplished.

4. Filtering Out the Noise

Not every report entry is worth including. Generic statements like “working on…” or “following up” don’t convey meaningful work. We built a bad‑word filter, one of key components of our intelligent document processing (IDP) pipeline. It flags entries containing these vague phrases.

The LLM processes each chunk and identifies data that match our exclusion list. In our test, this filter removed 69.1% of entries and only 29 items out of 94 survived the cut. What remained were concrete, specific descriptions of completed tasks.

5. Selecting the Best Candidates

Once we have a clean set of candidates, we need to choose the top N entries to present. The number N varies by project and is stored in our internal reporting database. To account for further filtering in the next step, we typically select a larger pool, say, 80 items.

6. Vector Duplicate Detection: Ensuring We Never Repeat Ourselves

This is the secret sauce that prevents duplicate entries. Before finalizing the list, the AI agent compares each candidate against a historical database of all work items we’ve ever submitted for that project. Here’s how it works:

1. Embedding Generation. Each work item is converted into a vector (a list of numbers) using the nomic‑embed‑text model. This vector captures the semantic meaning of the text;

2. Similarity Calculation. The system compares the new candidate’s vector against the vectors of all previously stored data for that project;

3. Threshold Decision. If the similarity score exceeds 0.85 (85%), the candidate is flagged as a duplicate and removed. This threshold catches not just exact matches but also near‑duplicates where the phrasing or word order has changed while the underlying idea remains the same.

The historical data is stored in a lightweight PostgreSQL table with just a few fields: project_id, text (the final description), embedding (the vector), and created_at (date of creation).

After duplicate removal, we’re left with a set of truly unique, high‑quality work items. These are then formatted for final delivery to the project manager.

Read Also Using AI to Generate a List of Works in Construction

Real‑World Performance: What Test Run Tells Us

Let’s walk through an actual test run to see the numbers in action. These test run results demonstrate how an AI report analysis tool can summarize reports into tasks even with noisy, inconsistent input.

Technical Deep Dive: Why CPU‑Only Deployment Works

One of the most common objections to running local LLMs is the perceived need for expensive GPU hardware. We deliberately chose a CPU‑only deployment to keep costs manageable and to prove that on‑premise AI doesn’t require significant infrastructure investments.

Model Selection: Gemma 4 E2B

We evaluated several local models and settled on Gemma 4 E2B. Here’s why:

• Size. At 5 billion parameters, it fits comfortably in RAM without needing a GPU. Our server has extra memory allocated specifically for the model;

• Performance. It’s fast enough for batch processing;

• Quality. The model handles JSON output reliably, and follows detailed prompts with minimal hallucination.

NOTE: If you work with a multilingual team, make sure that the model you use understands target languages natively.

Proper Model Settings and Prompt Engineering for Consistency

Each pipeline stage has its own carefully crafted prompt that includes:

• A clear role definition (e.g., “You are a specialized Data Parsing Engine”);

• Good examples and bad examples of expected output;

• Explicit formatting rules (JSON structure, field names);

• Instructions to avoid creativity (temperature set to 0).

For the bad‑word filter, we provide a list of prohibited terms and their synonyms: “working on,” “following up,” “in progress,” “discussed,” etc. The LLM simply acts as a pattern matcher with semantic understanding. It can recognize that “still working on the header” is conceptually similar to “in progress” and flag it accordingly.

Also, for data‑processing tasks like this, we always disable “thinking” or “chain‑of‑thought” modes. Those are useful for complex reasoning but introduce unnecessary variability and output length in structured extraction tasks.

Extra Challenges We Overcame

Challenge 1: LLM Unpredictability. Even with temperature set to 0, LLMs can occasionally produce unexpected output. We added timeout limits to prevent the model from getting stuck in a loop, and we structured our prompts to request strictly formatted JSON that is easy to validate programmatically.

Challenge 2: CPU Processing Speed. Processing 94 items across multiple LLM calls takes time. We solved this by running the AI agent as an overnight cron job, so speed is never a bottleneck. The manager arrives in the morning to a ready‑to‑review list.

Why This Approach Matters for Enterprise Clients

1. Complete Data Sovereignty

When you use on-premise Artificial Intelligence solutions, no data ever leaves your infrastructure. The LLM runs locally, the embedding model runs locally, and the historical database resides on your own PostgreSQL server.

2. No Vendor Lock‑In

Cloud AI services change their pricing, deprecate models, or alter their APIs without notice. By using local AI agents and Ollama, you retain full control over the entire stack. Need to switch to a different model tomorrow? Just pull a new one and update the configuration.

3. Predictable Costs

The only ongoing cost is the electricity to run the server. There are no per‑token API fees, no monthly subscriptions, and no surprise bills after a particularly busy month of processing. For organizations that process thousands of reports annually, the savings are substantial.

4. Customizable to Your Workflow

Because we own the code, we can adapt the pipeline to fit your specific reporting format, integrate with your existing PM tools, and fine‑tune the prompts to match your industry’s terminology. This enables using AI for business process automation across diverse sectors, from construction to healthcare.

From Manual Chore to Automated Precision

Before, turning chaotic developer notes into clean reports meant choosing between tedious manual work or exposing sensitive data to cloud AI. Our private AI agent for document analysis offers a third way. Namely, secure, on‑premise automation.

By combining Gemma 4 on standard CPU hardware with vector‑based duplicate detection and direct Jira enrichment, we’ve turned hours of monthly review into a hands‑off process. The system normalizes vague entries, filters out noise, and guarantees you never repeat a task description.

The answer to these issues is Capacitor. Created as a modern, “spiritual successor” to Cordova, Capacitor offers a practical and low-risk migration path. This article will walk you through why Cordova-to-Capacitor migrations make sense, how Capacitor differs from its predecessor, and how to navigate the transition smoothly.

Why Teams Are Moving Away from Cordova

The decision to move away from a familiar tool like Cordova is rarely about chasing trends. It allows solving concrete business and technical pain points. For development teams with apps in production, these frustrations become daily obstacles to delivering value:

• An Outdated and Stagnant Plugin Ecosystem. Cordova’s historical strength is its vast plugin library. However, it has become its biggest weakness. Many plugins are 5 to 7 years old, unmaintained, and break with new OS releases. Finding a modern, secure plugin for basic tasks can be a challenge, and when issues arise, the community support is often minimal;

• Slower Development Cycles. The combination of outdated tooling and a clunky build process directly impacts delivery speed. What should be a quick fix or a new feature can turn into a multi-day investigation into why a plugin isn’t working with the latest iOS version;

• Signs of a Fading Platform. Major industry moves, like Microsoft App Center deprecating Cordova support in 2022, signal a clear trend. While the project isn’t dead, outdated plugins and waning corporate investment make it a risky bet for long-term projects.

Capacitor as a Natural Evolution

Capacitor shares the same core philosophy as Cordova. It enables building mobile apps with web technologies, but executes it with a modern architectural approach.

Web-First, Not Web-Wrapped

Your web app is the core of your project. It’s simply copied into the native project as an asset. Although, you should expect to make UI/UX adjustments to optimize for mobile interaction patterns and screen sizes.

Direct Native Access

Capacitor gives you the flexibility to step outside the web view when your requirements demand it. For instance, if your app needs to render complex 3D graphics with Metal, you can open the project in Xcode or Android Studio and write Swift or Kotlin code directly. This eliminates Cordova’s “black box” feeling and gives you the same level of control as a fully native app. However, for most standard features (camera, geolocation, biometric authentication, or file storage), Capacitor’s official plugins provide everything you need.

Backward Compatibility

Capacitor provides a compatibility layer that allows a vast majority of existing Cordova plugins to work out of the box. This is the linchpin of a low-risk migration strategy. You can move the entire app over and then gradually replace plugins. There’s even this VS Code extension that helps developers detect what Cordova plugins can be replaced with Capacitor analogs.

Technology Longevity & Ecosystem Stability

For business decision-makers, the stability and future of a platform are paramount. Unlike Cordova, Capacitor has active support, evidenced by the release of version 8 in December 2025 and the continued development. Backed by Ionic, a company with a long-standing commitment to the open-source community, this corporate investment guarantees a level of stability and active development that the Cordova project currently lacks.

The ecosystem around Capacitor is vibrant and growing. It boasts a set of well-maintained official plugins, a thriving community creating their own, and strong integration with modern build tools. Capacitor’s ecosystem feels alive and ready for the future.

Why Not Just Using Good Old React Native Instead?

While Capacitor is the most logical upgrade path for existing Cordova apps, it’s not the only modernization strategy available. Depending on your business model, user expectations, and reliance on native device features, you might also consider React Native or even reevaluate whether you need a store-distributed mobile app at all.

Complete UI Rewrite (But That’s Not the Hardest Part)

Yes, React Native requires replacing HTML elements with native components and converting CSS to JavaScript objects. While this is a tedious task, AI tools can now handle much of the monotonous conversion work with the right prompting.

Legacy Code Complexity

A full rewrite forces you to confront not just UI conversion, but also refactoring messy code, addressing known bugs, and deciding whether to incorporate business logic or design changes that have accumulated over time. If your team lacks the bandwidth for this level of simultaneous cleanup, a React Native migration becomes a high-risk endeavor.

Higher Cost and Longer Timeline

A full rewrite means months of development, extensive testing, and a massive upfront investment. For an app that already works and serves its users well, this is often an unjustifiable business expense.

Skillset Shift

React Native development requires specialists who understand its unique paradigm. While Capacitor also involves bridging to native modules, the learning curve is gentler for developers with a pure web background. The core development tools remain the same, and they primarily need to learn the build, deployment, and plugin workflows, with plenty of guidance available through tools like the VS Code extension.

Choosing Between Capacitor, React Native, and PWA

For some businesses, especially those primarily delivering content or lightweight transactional services, moving from Cordova to a PWA can eliminate native maintenance overhead entirely. However, if your app depends heavily on device APIs, background processes, or advanced native SDK integrations, Capacitor offers a more future-proof path while keeping your web investment intact.

*A Progressive Web App is essentially a website that behaves like a mobile app. It can be installed on a device, work offline, and send push notifications, but it runs in a browser and is distributed via the web rather than app stores.

Business Benefits of Migrating from Cordova to Capacitor

The technical advantages of Capacitor translate directly into tangible business outcomes.

• Faster Feature Delivery. With a clean native layer, live reload, and a modern plugin ecosystem, developers can ship new features and updates much faster. Plus, Capacitor’s OTA (over-the-air) update capability, similar to React Native, lets push JS updates directly to users, which translates to faster Time-to-Market for new features and a quicker response to customer needs.;

• Reduced Maintenance Overhead. No more frantic Googling for unmaintained plugins or debugging obscure build errors. Capacitor’s predictable structure and well-documented upgrade paths lower your app’s technical debt. This means reduced operational expenses (OPEX) and more development budget allocated to building new features rather than fighting legacy issues.;

• Easier and Cheaper Hiring. You can hire from the vast pool of React, Vue, or Angular web developers. You are not locked into a niche market of Cordova or React Native specialists, which can significantly reduce team costs;

• Risk-Controlled Modernization. The migration can be done incrementally, without stopping development. You can move the app to Capacitor, and then slowly replace Cordova plugins with native Capacitor ones, ensuring stability at every step. This approach also serves as a stepping stone if you’re considering React Native down the road. If the app initially didn’t use React, developers can gradually move the codebase to React while on Capacitor, making a future transition to React Native significantly smoother and faster if business needs eventually require it.

The ability to move incrementally, documenting, rewriting, and testing features one by one, ensures that your day-to-day business operations and development cycles never skip a beat. It reduces business risk and accelerates your time-to-market with a stable, future-proof application.

How to Mitigate Common Migration Issues

Migrating from Cordova to Capacitor is designed to be a low-risk process, but it’s wise to be aware of common hurdles. XB Software’s experience guiding clients through complex app modernization projects shows that a smooth transition relies on anticipating a few key hurdles.

Your existing Cordova app likely relies on a set of plugins for native functionality. A common concern is that you’ll need to find or build a new plugin for every single feature, a process that could balloon project costs.

Solution: A Phased, Low-Risk Investment. Capacitor was built with backward compatibility in mind. Your team can first migrate the entire app while still using your existing Cordova plugins. Replacing old plugins with Capacitor equivalents becomes a separate, planned task. It can be done in various ways, such as searching for community Capacitor plugins, checking if functionality is available via web APIs, writing a custom Capacitor plugin, etc.

Even when a Capacitor equivalent for a Cordova plugin exists, the way your code talks to it might be different. If a developer has to refactor every screen that uses the camera or file system, a simple migration can quickly turn into a major timeline risk.

Solution: An “Adapter” Strategy to Protect Timelines. Development teams can build a simple “adapter” layer. This is a small piece of code that acts as a translator, allowing your existing application code to keep using its old commands while the adapter converts them into the new Capacitor plugin’s language. This decouples the migration of your business logic from the migration of your native features, keeping the project moving forward on schedule and allowing for thorough, risk-free testing of each new plugin integration.

Conclusion: Modernization Without Breaking What Works

Migrating from Cordova to Capacitor is a pragmatic, low-risk strategy that honors your investment in your web codebase while shedding the technical debt of an aging native layer. By choosing Capacitor, you’re opting for faster delivery, lower costs, and a development experience that your team will actually enjoy. You’re building a foundation that can adapt to the next five years of mobile innovation as smoothly as it handles today’s. And most importantly, you’re doing it without breaking what already works for your users.

This is where Spec-Driven Development (SDD) comes in. This methodology shifts the focus from vibe coding to following the general intent, using specifications as the new source of truth for AI-assisted engineering.

Why Vibe Coding Isn't Built to Last

The term "vibe coding" perfectly captures the current experimental phase of AI-assisted development. You describe what you want, get a block of code back, and if it looks right and seems to work, you move on. This approach is undeniably powerful for prototypes and small scripts, allowing for unprecedented velocity. However, when applied to serious, mission-critical applications, the cracks begin to show:

• The code might compile and even function, but the underlying architecture becomes an afterthought;

• New features create unexpected conflicts;

• Documentation is sparse or non-existent;

• The codebase transforms into a collection of disjointed components that are hard to maintain, debug, and evolve.

The problem isn't the AI's coding ability. It's rather the workflow where developers treat AI like a search engine when they should be treating it like a literal-minded, but exceptionally talented, pair programmer who needs unambiguous instructions.

Read Also How to Build a Custom Scheduling App Faster with Lovable AI and DHTMLX Scheduler

What Is Spec-Driven Development

Spec-Driven Development is the practice of writing clear, structured, and testable specifications before a single line of code is generated. In the context of AI-assisted development, SDD provides the blueprint that guides AI agents to generate code that is consistent, architecturally sound, and perfectly aligned with business goals.

Unlike traditional waterfall requirements that gather dust, an SDD spec is a living, executable artifact. It becomes the shared source of truth for both humans and AI, driving development, software testing, validation, and even documentation. By moving architectural decisions, constraints, and clarity upstream, SDD directly addresses the shortcomings of vibe coding. It replaces guesswork with a clear contract for how your app should behave.

How Spec-Driven Development Works: A Step-by-Step Guide

The SDD process is structured into distinct, sequential phases. Each phase produces a key artifact that feeds into the next, ensuring a clear, traceable path from a high-level idea to production-ready code.

1. Specify (The "What" and "Why"). You start with a high-level description of what you're building and why. The AI then generates a detailed functional specification. This phase is purely about business intent: user journeys, success criteria, and edge cases. It explicitly excludes technical details, forcing clarity on the problem before jumping to a solution;

2. Plan (The "How"). With the functional spec locked in, you provide the AI with your desired stack, architecture, and constraints. The AI generates a comprehensive technical plan, including technology choices, system design, integration patterns, and security considerations. This ensures the new code feels native to your project and aligns with your technical strategy;

3. Tasks (The Breakdown). The AI takes the spec and plan and breaks them down into small, reviewable, and actionable tasks. Each task is specific enough to be implemented and tested in isolation, like "create a user registration endpoint that validates email format." This decomposition prevents the "big bang" coding approach that overwhelms both AI and reviewers;

4. Implement (The Execution). Finally, the AI tackles the tasks one by one. Instead of reviewing thousand-line code dumps, developers review focused changes that solve specific problems, verifying that the implementation matches the specification.

Read Also AI as a Co-Pilot, Not an Autopilot: Guidance on Risk Management and Realistic Performance

A Quick Look at the Tools Enabling SDD

The SDD ecosystem is maturing rapidly. While GitHub's Spec Kit is a powerful open-source example, other platforms offer different interpretations of the model:

Spec Kit

An open-source CLI and template-based toolkit that integrates with your existing AI assistants like Copilot, Claude Code, and Gemini CLI. It introduces the concept of a constitution.md, a file that encodes your project's immutable principles, such as stack versions, naming conventions, and architectural patterns.

Kiro

An agentic AI with an IDE and CLI that add structure to an existing editor. Kiro has SDD built directly into its core. When starting a new feature, its agents automatically generate requirements, design documents, and create task lists, guiding the developer through an opinionated workflow. It's designed for developers who want a deeply integrated, automated, and context-aware environment for moving from concept to code.

BMAD Method

An open-source framework that simulates an entire agile team using specialized AI agents. With over 12 distinct agent personas, including a Product Manager, Architect, Scrum Master, etc., it manages the entire project lifecycle.

XB Software’s Experience: Putting Spec Kit to the Test

Theory is one thing, but practice is where the real lessons are learned. Our team recently dove into GitHub’s Spec Kit to understand its practical applications and limitations. Here’s what we found trying to recreate the app shown below. It’s a small fleet management dashboard with a scheduler, a map, and vehicle tables:

Fleet Management System Demo

How Spec Kit Works

• /constitution:

  • When to use: At the very beginning of a project.

  • Purpose: Establishes your project's foundational rules, defining the tech stack, architectural patterns, and coding conventions that AI-generated code must follow.

• /specify:

  • When to use: After the constitution is set.

  • Purpose: Takes your high-level, plain-language description of a feature (the "what" and "why") and expands it into a detailed functional specification.

• /plan:

  • When to use: After the specification is reviewed and approved.

  • Purpose: Generates a technical implementation plan based on the spec and the project's constitution, defines frameworks, libraries, etc.

• /tasks:

  • When to use: After the plan is finalized.

  • Purpose: Breaks down the specification and plan into a list of small, concrete, and actionable tasks. Each task is designed to be implemented and tested independently.

• /implement:

  • When to use: After the tasks are defined.

  • Purpose: Instructs the AI agent to start writing the actual code, working through the generated task list one by one.

Our web development team started by testing the limits of the process. The first attempt was to generate a complete demo application, in one go. The high-level description was fed into the /specify command, and the results quickly revealed the AI's contextual limitations. The application generated by Spec Kit was a mess:  the scheduler rendered strangely, filters didn't work, and the statistics pulled random data not connected to the users or vehicles:

This shows that feeding too much information at once simply overwhelms the model. It gets confused and starts losing track of early requirements halfway through implementation.

The failure illustrated a core principle of SDD: decomposition is not optional. The AI's context window, while large, has finite capacity. Handling a complex, multi-page application in one go leads to forgotten requirements and inconsistent results.

A better strategy is to build the project feature by feature. On the second attempt, our team started with the core layout (the header and collapsible menu) with a highly detailed spec that included exact styles and components:

Next came the "vehicles" page, specified down to the placement of inputs, instructing the AI to match the layout of a provided demo. While it wasn't perfect, and the AI still decided to paint a button a different color, it was a manageable, high-quality chunk of work that could be easily corrected with a follow-up prompt or a quick manual tweak.

The final step was a tiny, well-scoped feature: adding sorting to two columns in an existing table. The simple command create client-sorting for type and year columns on Vehicle Stable proved perfectly suited for the SDD workflow, demonstrating that the methodology's value extends to changes of any size, ensuring even small updates are implemented correctly and consistently:

Our experiments with Spec Kit revealed that successful AI-assisted development hinges on proper decomposition. Attempting to generate an entire application in one pass overwhelmed the model and produced unusable results, while breaking the project into small, well-scoped features consistently delivered high-quality, reviewable code. The key insight: specifications must match the size of the task, ensuring AI can maintain focus and consistency throughout implementation.

When SDD Makes the Most Sense

It is not a silver bullet for every coding task, but it provides immense value in specific scenarios:

• Enterprise & Production Systems. For long-lived applications where maintainability, stability, and compliance are critical;

• Complex Architectures. For projects with multiple services, APIs, and integration points where a lack of clarity can lead to catastrophic failure;

• Team Development. When multiple developers (and AI agents) need to collaborate on a shared codebase, a central source of truth is invaluable;

• Legacy Modernization. When rebuilding an old system, you can use SDD to capture the essential business logic in a modern spec before letting AI regenerate a clean, new implementation.

Conclusion: From Code-Centric to Spec-Centric Thinking

We are moving from an era where "code is the source of truth" to one where "intent is the source of truth." AI is making specifications executable, turning our documented intent directly into working software. Spec-Driven Development allows small teams to build robust systems and large organizations to move with coherence and speed.