spec-suite-skill

Why I Built Spec Suite: Putting an End to Hallucinated AI Documentation

Let's be honest about the current state of AI-assisted software planning: we've all tried asking a Large Language Model (LLM) or a CLI agent to write a "Technical Requirements Document" or a "Terms of Service" policy. We paste a massive prompt, cross our fingers, and wait.

The result? Usually, it's a generic wall of text. The AI invents database paradigms you don’t use, ignores your specific user roles, and if you ask for a legal policy, it completely forgets to include the mandatory liability disclaimers.

I got tired of wrestling with these "hallucinations" and spending more time fixing AI-generated documents than it would take to write them from scratch. That frustration led to the creation of Spec Suite.

The Core Problem: Lack of Contextual Discipline

LLMs are incredibly smart, but they lack discipline. If you ask an autonomous agent to build a Security Threat Model, it will gladly oblige by guessing your architecture.

To fix this, we don't need better prompts; we need a structured prompt ecosystem. Agents need to understand that documentation is a dependency graph. You cannot write a Security Plan without first establishing the System Architecture (TRD) and the Database Schema. You cannot write a Data Processing Policy without knowing the jurisdictions you operate in.

Enter Spec Suite

Spec Suite is an open-source orchestration skill designed specifically for autonomous AI agents (like Claude Code, Antigravity, Cursor, etc.). Instead of giving the AI loose instructions, Spec Suite teaches your agent to behave like a methodical Senior Software Architect and a rigorous Compliance Expert.

It achieves this by dividing project documentation into two distinct, interconnected tracks:

💻 Track A: The Technical Specs

This track focuses on the engineering blueprints. It guides the AI to produce:

1. PRD (Product Requirements Document)
2. TRD (Technical Requirements Document & Architecture)
3. Backend Schema (Database ERDs and indexing strategies)
4. App Flow (User journeys and event-driven system flows)
5. UI/UX Brief (Information architecture and accessibility rules)
6. Implementation Plan (Phased delivery and risk registries)
7. Security Plan (Threat modeling and defense-in-depth)

⚖️ Track B: The Legal & Policy Suite

This track focuses on compliance and operations. The agent acts as a policy drafter, always enforcing mandatory "Structural Draft" disclaimers:

1. Legal Compliance Annex (Jurisdictional mapping)
2. Terms of Service (T&C)
3. Privacy Policy (PII handling and user rights)
4. Data Processing Policy (Data lifecycles and vendor mapping)
5. Acceptable Use Policy (Content moderation and enforcement)
6. Content & Image Use Policy (Copyright and UGC rules)
7. AI Use Policy (Governance for algorithmic decision-making)
8. Disclaimer & Continuity (SLAs and warranties)

The Magic: Prerequisite Chaining

What makes Spec Suite powerful isn't just the markdown templates; it's how the AI is instructed to use them.

Embedded within the skill is a strict set of prerequisite rules. If you tell your agent, "Generate a Security Plan", the agent is programmed to stop and verify its context. It will essentially tell you: "Wait, I cannot write a Security Plan without first reading your TRD and Backend Schema."

If those documents don't exist in your project yet, the agent will offer to generate them first. This prerequisite chaining forces the LLM to anchor its outputs to established facts about your project, drastically reducing hallucinations. The resulting documents are highly cohesive because the AI is literally building on its own validated context.

Lightning-Fast Sub-Module Routing

You don't always need to generate a massive 15-document suite. Sometimes you're just hacking in your terminal and realize you need a quick database schema for a new feature.

Spec Suite includes an alias-based sub-module routing system. You can simply tell your agent:
Execute spec-suite:schema for this feature

The agent bypasses the master orchestrator, reads the specific guidelines for database schemas, asks you for the target output directory, and generates exactly what you need in seconds.

Try It In Your Project

I've made Spec Suite completely Open Source (MIT License). If you are using NPM-compatible autonomous agents, you can install it globally or inject it directly into your current workspace with a single command:

npx @abdiel49/spec-suite-skill

The next time you start a new project, try telling your agent: "Generate the full spec suite for this idea." Grab a coffee, and watch it meticulously orchestrate your entire technical and legal foundation.

If Spec Suite saves you hours of documentation headaches (like it has for me), consider giving it a star on GitHub or reaching out on Twitter to share your experience. Happy coding!