structured-plan

README

Structured Plan

A unified planning system with Go data types, JSON serialization, and markdown generation. Supports requirements documents, goal frameworks, and roadmaps.

Overview

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

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

Goal Frameworks

• OKR - Objectives and Key Results: Objectives with measurable key results and phase targets
• V2MOM - Vision, Values, Methods, Obstacles, Measures: Salesforce-style goal alignment

Roadmap

• Roadmap - Standalone roadmaps with phases, deliverables, and swimlane visualization

The natural workflow from market to implementation:

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

Each document type supports:

• Mandatory and optional sections for flexibility
• JSON serialization with Go types (camelCase field names)
• Markdown generation with Pandoc-compatible YAML frontmatter
• Validation of required fields
• Framework-agnostic goals (OKR or V2MOM)

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
splan req prd generate input.json --text-icons    # ASCII icons for Pandoc PDF

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

Requirements Documents

package main

import (
    "encoding/json"
    "os"

    "github.com/grokify/structured-plan/requirements/prd"
    "github.com/grokify/structured-plan/requirements/mrd"
    "github.com/grokify/structured-plan/requirements/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)
}

Goals (OKR and V2MOM)

The goals package provides a framework-agnostic interface for both OKR and V2MOM:

import (
    "github.com/grokify/structured-plan/goals"
    "github.com/grokify/structured-plan/goals/okr"
    "github.com/grokify/structured-plan/goals/v2mom"
)

// Create OKR-based goals
okrSet := okr.OKRSet{
    Objectives: []okr.Objective{
        {
            ID:          "obj-1",
            Description: "Increase customer satisfaction",
            KeyResults: []okr.KeyResult{
                {ID: "kr-1", Description: "NPS score", Target: "> 50"},
            },
        },
    },
}
g := goals.NewOKR(okrSet)

// Or create V2MOM-based goals
v := v2mom.V2MOM{
    Vision: "Be the market leader",
    Methods: []v2mom.Method{
        {ID: "m-1", Description: "Launch enterprise features"},
    },
}
g := goals.NewV2MOM(v)

// Framework-agnostic access
for _, item := range g.GoalItems() {
    fmt.Println(item.Description())  // Works with both OKR and V2MOM
}

// Dynamic labels based on framework
fmt.Println(g.GoalLabel())   // "Objectives" (OKR) or "Methods" (V2MOM)
fmt.Println(g.ResultLabel()) // "Key Results" (OKR) or "Measures" (V2MOM)

PRD with Goals

PRDs support framework-agnostic goals via the ProductGoals field:

import (
    "github.com/grokify/structured-plan/requirements/prd"
    "github.com/grokify/structured-plan/goals"
)

doc := prd.Document{
    // ... metadata, executive summary, etc.
    ProductGoals: goals.NewOKR(okrSet),  // or goals.NewV2MOM(v2mom)
}

// Roadmap tables use correct terminology automatically
table := doc.ToSwimlaneTableWithGoals(opts)  // Uses "Objectives" or "Methods"

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:

Category	Weight	Description
problem_definition	20%	Problem statement clarity and evidence
solution_fit	15%	Solution alignment with problem
user_understanding	10%	Persona depth and user insights
market_awareness	10%	Competitive analysis
scope_discipline	10%	Clear objectives and boundaries
requirements_quality	10%	Functional and non-functional specs
metrics_quality	10%	Success metrics with targets
ux_coverage	5%	Design and accessibility
technical_feasibility	5%	Architecture and integrations
risk_management	5%	Risk identification and mitigation

Document Types

MRD - Market Requirements Document

Defines the market opportunity and business justification.

Section	Required	Description
metadata	Yes	Document ID, title, version, authors
executiveSummary	Yes	Market opportunity, proposed offering, key findings
marketOverview	Yes	TAM/SAM/SOM, growth rate, trends
targetMarket	Yes	Primary/secondary segments, buyer personas
competitiveLandscape	Yes	Competitors, strengths/weaknesses, differentiators
marketRequirements	Yes	Market-level requirements with priorities
positioning	Yes	Positioning statement, key benefits
goToMarket	No	Launch strategy, pricing, distribution
successMetrics	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
executiveSummary	Yes	Problem statement, proposed solution, outcomes
objectives	Yes	Business objectives, product goals, success metrics
personas	Yes	User personas with goals and pain points
userStories	Yes	User stories with acceptance criteria
requirements.functional	Yes	Functional requirements (MoSCoW priority)
requirements.nonFunctional	Yes	NFRs (performance, security, etc.)
roadmap	Yes	Phases with deliverables and success criteria
assumptions	No	Assumptions, constraints, dependencies
inScope	No	Explicitly included items
outOfScope	No	Explicitly excluded items
technicalArchitecture	No	System overview, integrations, services, APIs
relatedDocuments	No	Links to related PRDs, TRDs, design docs
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
executiveSummary	Yes	Purpose, scope, technical approach
architecture	Yes	Overview, principles, components, data flows
technologyStack	Yes	Languages, frameworks, databases, infrastructure
apiSpecifications	No	API definitions with endpoints
dataModel	No	Entities, attributes, data stores
securityDesign	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
painPoints	Yes	Current frustrations
behaviors	No	Typical behaviors and patterns
technicalProficiency	No	Low, Medium, High, Expert

User Stories

Field	Required	Description
id	Yes	Unique story identifier
personaId	Yes	Reference to persona
title	Yes	Short descriptive title
story	Yes	"As a [persona], I want [goal] so that [reason]"
acceptanceCriteria	Yes	Testable conditions (Given/When/Then)
priority	Yes	Critical, High, Medium, Low
phaseId	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

{
  "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)

Type Value	Swimlane Row	Description
feature	Features	Product features and capabilities
integration	Integrations	Third-party integrations
infrastructure	Infrastructure	Platform, CI/CD, monitoring
documentation	Documentation	User guides, API docs
milestone	Milestones	Release milestones, checkpoints
rollout	Rollout	Customer/segment deployment phases

Deliverable Status Icons

Status Value	Icon	Description
completed	✅	Work is done
in_progress	🔄	Currently being worked on
not_started	⏳	Planned but not started
blocked	🚫	Blocked by dependency

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

Problem	Cause	Solution
Item not appearing	Missing or invalid type	Set type to a valid value
Item in wrong row	Wrong type value	Check spelling (e.g., feature not Feature)
Item in wrong column	Wrong phase	Move deliverable to correct phase's array
No status icon	Missing status field	Add status field with valid value

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:

Swimlane	Phase 1 Q1 2026	Phase 2 Q2 2026	Phase 3 Q3 2026
Features	• Auth • Dashboard	• Reporting • API v2	• Analytics
Rollout		• ✅ Auth → Enterprise • 🔄 Dashboard → Pilot	• Reporting → All

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

Category	Description	Example Metrics
performance	Response time, throughput	P95 < 200ms
scalability	Scaling capability	10K concurrent users
reliability	Uptime, MTBF, MTTR	99.9% uptime
security	AuthN, AuthZ, encryption	SOC 2 compliance
multiTenancy	Tenant isolation	Schema-per-tenant
observability	Logging, metrics, tracing	100% trace coverage
compliance	Regulatory requirements	GDPR, HIPAA

Technical Architecture (Platform PRDs)

For platform and infrastructure PRDs, the technicalArchitecture section supports microservices documentation:

Services Inventory

Field	Required	Description
id	Yes	Unique service identifier
name	Yes	Service name
description	Yes	What the service does
layer	No	control-plane, execution-plane, data-plane, gateway
protocol	No	REST, gRPC, GraphQL, WebSocket
language	No	Primary programming language
languageRationale	No	Why this language was chosen
responsibilities	No	List of service responsibilities
dependencies	No	IDs of dependent services

API Specifications

Field	Required	Description
name	Yes	API name
protocol	Yes	REST, gRPC, GraphQL, WebSocket
basePath	No	Base URL path
version	No	API version
endpoints	No	List of endpoints (method, path, description, auth)
openApiSpec	No	URL to OpenAPI/Swagger spec
protobufSpec	No	URL to protobuf definitions

Storage Architecture

Field	Required	Description
category	Yes	metadata, artifacts, state, cache, observability, audit, secrets
purpose	Yes	What this storage is for
technology	Yes	Storage technology (DynamoDB, S3, etc.)
encryption	No	Encryption approach
retention	No	Data retention policy
perTenant	No	Whether storage is isolated per tenant

GitOps Configuration

Field	Required	Description
enabled	Yes	Whether GitOps is used
provider	No	GitOps provider (ArgoCD, Flux, etc.)
workflow	No	GitOps workflow description
sourcesOfTruth	No	List of artifacts and their locations (git, s3, database, secrets-manager, registry)

Workflow Orchestration

Field	Required	Description
shortLived	No	Engine for short-lived workflows (Step Functions, etc.)
longRunning	No	Engine for long-running workflows (Temporal, etc.)
description	No	Orchestration approach description

Related Documents

Link to related PRDs, TRDs, and design documents:

Field	Required	Description
id	Yes	Document identifier
title	Yes	Document title
type	Yes	prd, trd, mrd, design-doc, rfc
relationship	Yes	child, parent, sibling, implements, supersedes, related
path	No	File path to document
url	No	URL to document
description	No	Relationship context

MRD Details

Market Size (TAM/SAM/SOM)

Field	Required	Description
value	Yes	Market size (e.g., "$10B")
year	No	Reference year
source	No	Data source citation
notes	No	Additional context

Buyer Personas

Field	Required	Description
id	Yes	Unique identifier
name	Yes	Persona name
title	Yes	Job title
buyingRole	Yes	Decision Maker, Influencer, User, Gatekeeper
budgetAuthority	Yes	Has budget authority (boolean)
painPoints	Yes	Business pain points
goals	Yes	Business goals
buyingCriteria	No	Purchase decision criteria

Competitors

Field	Required	Description
id	Yes	Unique identifier
name	Yes	Competitor name
category	No	Direct, Indirect, Substitute
strengths	Yes	Competitive strengths
weaknesses	Yes	Competitive weaknesses
marketShare	No	Market share percentage
threatLevel	No	High, Medium, Low

TRD Details

Architecture Components

Field	Required	Description
id	Yes	Component identifier
name	Yes	Component name
description	Yes	What it does
type	No	Service, Library, Database, Queue, etc.
responsibilities	No	List of responsibilities
dependencies	No	IDs of dependent components
technology	No	Implementation technology

API Specifications

Field	Required	Description
id	Yes	API identifier
name	Yes	API name
type	Yes	REST, gRPC, GraphQL, WebSocket
version	No	API version
baseUrl	No	Base URL
auth	No	Authentication method
endpoints	No	List of endpoints

Security Design

Field	Required	Description
overview	Yes	Security approach summary
authentication	No	AuthN method, provider, MFA
authorization	No	AuthZ model (RBAC, ABAC)
encryption	No	At-rest and in-transit encryption
compliance	No	Compliance standards (SOC2, GDPR)

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:

Section	Weight	What's Checked
Metadata	10%	ID, title, version, status, authors
Executive Summary	10%	Problem statement depth, proposed solution, outcomes
Objectives	10%	Business objectives, product goals, success metrics with targets
Personas	10%	Number of personas, completeness of goals/pain points
User Stories	10%	Acceptance criteria coverage, persona/phase linkage
Requirements	10%	Functional/non-functional count, essential NFR categories
Roadmap	10%	Phases with deliverables, success criteria, goals
Optional sections	30%	Assumptions, in/out of scope, tech architecture, UX, risks, glossary, related docs

Example Output

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

Overall Score: 90.8% (Grade: A)
Required Sections: 7/7 complete
Optional Sections: 5/8 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)
  [+] In Scope                  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)
  [ ] Related Documents           0.0% (missing)

-------------------------------------------------------------
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
pandoc myproduct.md -o myproduct.pdf

Requirements:

• Pandoc
• A LaTeX distribution (TeX Live, MacTeX, or MiKTeX)

Handling Status Icons (Emoji)

The default output uses emoji status icons (✅, 🔄, ⏳, etc.) which display correctly in HTML but may not render in PDF output. You have two options:

Option 1: Use text icons for PDF compatibility

opts := prd.DefaultMarkdownOptions()
opts.UseTextIcons = true  // Uses [DONE], [WIP], [TODO] instead of emoji
markdown := doc.ToMarkdown(opts)

Text icon mappings:

Emoji	Text Icon
✅	[DONE]
🔄	[WIP]
⏳	[TODO]
🚫	[BLOCKED]
❌	[MISSED]

Option 2: Use XeLaTeX with emoji-capable fonts

pandoc myproduct.md -o myproduct.pdf --pdf-engine=xelatex \
  -V mainfont="Noto Sans" \
  -V monofont="Noto Sans Mono"

Note: This requires fonts with emoji support (e.g., Noto Color Emoji, Apple Color Emoji).

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