structured-plan

Structured Requirements Documents

A structured format for requirements documents with Go data types, JSON serialization, and markdown generation. Supports three document types that form a natural workflow:

MRD (Market Requirements) → PRD (Product Requirements) → TRD (Technical Requirements)

Overview

This library provides comprehensive, machine-readable formats for requirements documents:

• MRD - Market Requirements Document: Market analysis, competitive landscape, buyer personas, positioning
• PRD - Product Requirements Document: Personas, user stories, functional/non-functional requirements, roadmap
• TRD - Technical Requirements Document: Architecture, technology stack, APIs, security design, deployment

Each document type supports:

• Mandatory and optional sections for flexibility
• JSON serialization with Go types
• Markdown generation with Pandoc-compatible YAML frontmatter
• Validation of required fields

Installation

Homebrew (macOS/Linux)

brew install grokify/tap/splan

Go Install

go install github.com/grokify/structured-plan/cmd/splan@latest

Download Binary

Pre-built binaries for Linux, macOS, and Windows are available on the releases page.

CLI Usage

The splan CLI provides commands for working with planning documents:

# PRD commands
splan requirements prd generate <file.json>   # Generate markdown from PRD
splan requirements prd validate <file.json>   # Validate PRD structure
splan requirements prd check <file.json>      # Check PRD completeness
splan requirements prd score <file.json>      # Score PRD quality
splan requirements prd filter <file.json>     # Filter PRD by tags

# MRD commands
splan requirements mrd generate <file.json>   # Generate markdown from MRD
splan requirements mrd validate <file.json>   # Validate MRD structure

# TRD commands
splan requirements trd generate <file.json>   # Generate markdown from TRD
splan requirements trd validate <file.json>   # Validate TRD structure

# Utility commands
splan merge file1.json file2.json -o out.json # Merge JSON files
splan schema generate                          # Generate JSON schemas

Shorthand: Use req instead of requirements (e.g., splan req prd generate).

Generate Options

splan req prd generate input.json -o output.md    # Custom output path
splan req prd generate input.json --no-frontmatter # Without YAML frontmatter
splan req prd generate input.json --margin 1in    # Custom page margin
splan req prd generate input.json --mainfont Arial # Custom font

Check Options (PRD only)

splan req prd check input.json          # Human-readable completeness report
splan req prd check input.json --json   # JSON output for programmatic use

Examples

# Validate and generate markdown
splan req mrd validate examples/agent-platform.mrd.json
splan req mrd generate examples/agent-platform.mrd.json

splan req prd validate examples/agent-control-plane.prd.json
splan req prd generate examples/agent-control-plane.prd.json
splan req prd check examples/agent-control-plane.prd.json

splan req trd validate examples/agent-control-plane.trd.json
splan req trd generate examples/agent-control-plane.trd.json

Library Usage

package main

import (
    "encoding/json"
    "os"

    "github.com/grokify/structured-plan/prd"
    "github.com/grokify/structured-plan/mrd"
    "github.com/grokify/structured-plan/trd"
)

func main() {
    // Create a PRD programmatically
    doc := prd.Document{
        Metadata: prd.Metadata{
            ID:      "prd-001",
            Title:   "User Authentication System",
            Version: "1.0.0",
            Status:  prd.StatusDraft,
            Authors: []prd.Person{{Name: "Jane Doe"}},
        },
        ExecutiveSummary: prd.ExecutiveSummary{
            ProblemStatement: "Users need secure authentication",
            ProposedSolution: "Implement OAuth 2.0 with MFA",
        },
        // ... additional fields
    }

    // Generate markdown
    opts := prd.MarkdownOptions{
        IncludeFrontmatter: true,
        Margin:             "2cm",
    }
    markdown := doc.ToMarkdown(opts)

    // Or marshal to JSON
    data, _ := json.MarshalIndent(doc, "", "  ")
    os.WriteFile("output.prd.json", data, 0600)
}

Evaluation Integration

The library integrates with structured-evaluation for standardized quality reports:

import "github.com/grokify/structured-plan/prd"

// Load and score a PRD
doc, _ := prd.Load("my-product.prd.json")

// Convert deterministic scoring to EvaluationReport format
report := prd.ScoreToEvaluationReport(doc, "my-product.prd.json")

// Or generate a template for LLM judge evaluation
template := prd.GenerateEvaluationTemplate(doc, "my-product.prd.json")

Standard Evaluation Categories:

## Document Types

### MRD - Market Requirements Document

Defines the market opportunity and business justification.

| Section | Required | Description |
|---------|----------|-------------|
| `metadata` | Yes | Document ID, title, version, authors |
| `executive_summary` | Yes | Market opportunity, proposed offering, key findings |
| `market_overview` | Yes | TAM/SAM/SOM, growth rate, trends |
| `target_market` | Yes | Primary/secondary segments, buyer personas |
| `competitive_landscape` | Yes | Competitors, strengths/weaknesses, differentiators |
| `market_requirements` | Yes | Market-level requirements with priorities |
| `positioning` | Yes | Positioning statement, key benefits |
| `go_to_market` | No | Launch strategy, pricing, distribution |
| `success_metrics` | Yes | Revenue targets, market share goals |
| `risks` | No | Market and competitive risks |
| `glossary` | No | Term definitions |

### PRD - Product Requirements Document

Defines what the product should do and for whom.

| Section | Required | Description |
|---------|----------|-------------|
| `metadata` | Yes | Document ID, title, version, authors |
| `executive_summary` | Yes | Problem statement, proposed solution, outcomes |
| `objectives` | Yes | Business objectives, product goals, success metrics |
| `personas` | Yes | User personas with goals and pain points |
| `user_stories` | Yes | User stories with acceptance criteria |
| `requirements.functional` | Yes | Functional requirements (MoSCoW priority) |
| `requirements.non_functional` | Yes | NFRs (performance, security, etc.) |
| `roadmap` | Yes | Phases with deliverables and success criteria |
| `assumptions` | No | Assumptions, constraints, dependencies |
| `out_of_scope` | No | Explicitly excluded items |
| `technical_architecture` | No | System overview, integrations |
| `risks` | No | Product and technical risks |
| `glossary` | No | Term definitions |

### TRD - Technical Requirements Document

Defines how the product will be built.

| Section | Required | Description |
|---------|----------|-------------|
| `metadata` | Yes | Document ID, title, version, authors |
| `executive_summary` | Yes | Purpose, scope, technical approach |
| `architecture` | Yes | Overview, principles, components, data flows |
| `technology_stack` | Yes | Languages, frameworks, databases, infrastructure |
| `api_specifications` | No | API definitions with endpoints |
| `data_model` | No | Entities, attributes, data stores |
| `security_design` | Yes | AuthN, AuthZ, encryption, compliance |
| `performance` | Yes | Performance requirements and benchmarks |
| `scalability` | No | Horizontal/vertical scaling, limits |
| `deployment` | Yes | Environments, strategy, regions |
| `integrations` | No | External system integrations |
| `development` | No | Coding standards, branch strategy |
| `testing` | No | Testing strategy and coverage |
| `risks` | No | Technical risks |
| `glossary` | No | Term definitions |

## File Naming Convention

Use these extensions for automatic type detection:

- `*.prd.json` - Product Requirements Document
- `*.mrd.json` - Market Requirements Document
- `*.trd.json` - Technical Requirements Document

## PRD Details

### Personas

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique persona identifier |
| `name` | Yes | Persona name (e.g., "Developer Dan") |
| `role` | Yes | Job title or role |
| `description` | Yes | Background and context |
| `goals` | Yes | What they want to achieve |
| `pain_points` | Yes | Current frustrations |
| `behaviors` | No | Typical behaviors and patterns |
| `technical_proficiency` | No | Low, Medium, High, Expert |

### User Stories

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique story identifier |
| `persona_id` | Yes | Reference to persona |
| `title` | Yes | Short descriptive title |
| `story` | Yes | "As a [persona], I want [goal] so that [reason]" |
| `acceptance_criteria` | Yes | Testable conditions (Given/When/Then) |
| `priority` | Yes | Critical, High, Medium, Low |
| `phase_id` | Yes | Reference to roadmap phase |

### Roadmap and Swimlane Table

The PRD roadmap is rendered as a swimlane table with phases as columns and deliverable types as rows.

#### Roadmap Structure

```json
{
  "roadmap": {
    "phases": [
      {
        "id": "phase-1",
        "name": "MVP",
        "deliverables": [
          {
            "id": "d1",
            "title": "User Authentication",
            "type": "feature",
            "status": "completed"
          }
        ]
      }
    ]
  }
}

Ensuring Items Appear in the Roadmap Table

For a deliverable to appear in the swimlane table:

1. Add to a Phase: The deliverable must be in a phase's deliverables array
2. Set the Type: The type field determines which swimlane row the item appears in
3. Set Status (optional): The status field adds a status icon

Deliverable Types (Swimlanes)

Deliverable Status Icons

Example: Complete Deliverable

{
  "id": "auth-feature",
  "title": "OAuth 2.0 Authentication",
  "description": "Implement OAuth 2.0 with support for Google and GitHub providers",
  "type": "feature",
  "status": "in_progress"
}

This appears in the Features row under the phase it belongs to, with a 🔄 icon.

Common Issues

Operational Rollout Swimlane

The rollout type enables tracking customer/segment deployments across phases. This is useful for phased go-to-market strategies where features are deployed to different customer segments over time.

Recommended approach for calendar-tied phases:

When phases represent calendar periods (quarters, months), place rollouts in the phase when deployment actually occurs, not when development completes:

Rationale:

• Reflects reality - Development and rollout rarely happen in the same calendar window
• Shows dependencies - Clearly communicates "build first, then deploy"
• Planning accuracy - Resource allocation aligns with actual work timing

Naming convention for rollout deliverables:

Use the → notation to distinguish rollout targets:

{
  "id": "rollout-auth-enterprise",
  "title": "Auth → Enterprise customers",
  "description": "Roll out Phase 1 Auth feature to enterprise segment",
  "type": "rollout",
  "status": "completed"
}

Example: Multi-phase customer rollout

{
  "phases": [
    {
      "id": "phase-1",
      "name": "Q1 2026 - Build",
      "deliverables": [
        { "id": "f1", "title": "User Authentication", "type": "feature", "status": "completed" },
        { "id": "f2", "title": "Dashboard", "type": "feature", "status": "completed" }
      ]
    },
    {
      "id": "phase-2",
      "name": "Q2 2026 - Pilot",
      "deliverables": [
        { "id": "f3", "title": "Reporting", "type": "feature", "status": "in_progress" },
        { "id": "r1", "title": "Auth → Enterprise (Acme, TechCo)", "type": "rollout", "status": "completed" },
        { "id": "r2", "title": "Dashboard → Pilot customers", "type": "rollout", "status": "in_progress" }
      ]
    },
    {
      "id": "phase-3",
      "name": "Q3 2026 - GA",
      "deliverables": [
        { "id": "r3", "title": "Auth → All customers", "type": "rollout", "status": "not_started" },
        { "id": "r4", "title": "Dashboard → All customers", "type": "rollout", "status": "not_started" },
        { "id": "r5", "title": "Reporting → Enterprise", "type": "rollout", "status": "not_started" }
      ]
    }
  ]
}

Non-Functional Requirements

MRD Details

Market Size (TAM/SAM/SOM)

Buyer Personas

Competitors

TRD Details

Architecture Components

API Specifications

Security Design

PRD Completeness Check

The splan req prd check command analyzes a PRD for completeness and quality, providing:

• Overall score (0-100%) and letter grade (A-F)
• Section-by-section breakdown for both required and optional sections
• Specific recommendations prioritized by severity

Scoring

The completeness check evaluates:

Example Output

=============================================================
PRD COMPLETENESS REPORT
=============================================================

Overall Score: 90.8% (Grade: A)
Required Sections: 7/7 complete
Optional Sections: 4/6 complete

-------------------------------------------------------------
SECTION BREAKDOWN
-------------------------------------------------------------

Required Sections:
  [+] Metadata                  100.0% (complete)
  [+] Executive Summary         100.0% (complete)
  [+] Objectives                100.0% (complete)
  [+] Personas                  100.0% (complete)
  [+] User Stories              100.0% (complete)
  [+] Requirements               83.3% (complete)
  [+] Roadmap                   100.0% (complete)

Optional Sections:
  [+] Assumptions & Constraints 100.0% (complete)
  [+] Out of Scope              100.0% (complete)
  [~] Technical Architecture     50.0% (partial)
  [ ] UX Requirements             0.0% (missing)
  [+] Risks                     100.0% (complete)
  [+] Glossary                  100.0% (complete)

-------------------------------------------------------------
RECOMMENDATIONS
-------------------------------------------------------------

HIGH (should fix):
  [*] Requirements: Missing NFR categories: reliability

=============================================================

PDF Generation

The generated markdown includes YAML frontmatter compatible with Pandoc:

# Generate markdown
splan req prd generate myproduct.prd.json -o myproduct.md

# Convert to PDF with Pandoc
pandoc myproduct.md -o myproduct.pdf --pdf-engine=xelatex

Examples

See the examples/ directory for complete examples:

• examples/agent-platform.mrd.json - Market requirements for an AI governance platform
• examples/agent-control-plane.prd.json - Product requirements for the control plane
• examples/agent-control-plane.trd.json - Technical requirements for implementation

References

Requirements Documents

• Modern Analyst - 9 Types of Requirements Documents
• Product School - PRD Template
• Atlassian - Product Requirements

Technical Documentation

• AWS - Architecture Documentation
• C4 Model - Software Architecture
• ADR - Architecture Decision Records

License

MIT License