Transform Functional Specification Documents (FSD) into Markdown-first technical artifacts — API specs, ERD schemas, UML diagrams, developer task cards, HTML Gantt timeline charts, and a Requirement Traceability Matrix — using AI-powered coding assistants like Cursor, Claude Code, OpenCode, or any agent that supports custom skills.
FSD Analyzer is a skill/plugin for AI coding assistants that acts as a Senior System Analyst. It reads your FSD or business requirements and produces:
| Output | Purpose |
|---|---|
| spec_api.md | REST API contract (endpoints, auth, validation, errors, examples) |
| erd.md + DBML | Database schema + paste-ready for dbdiagram.io |
| UML diagrams | PlantUML — sequence, class, activity, state, component, use case diagrams |
| task.md | Developer task cards with Story Points, dependencies, critical path (copy to Monday, Jira, Confluence) |
| task_fe.md | Frontend task cards (component breakdown, API integration, UI states, acceptance criteria) |
| timeline.html | Self-contained HTML Gantt chart with Story Points, dependencies, critical path, developer utilization |
| RTM | Requirement Traceability Matrix — business requirements → FR → design solution → test case (output/rtm/RTM.md / RTM_<scope>.md) |
| openapi.yaml | OpenAPI 3.0 consolidating all endpoint specs with x-status / x-phase (output/spec/openapi.yaml) |
| Gap Report | Structured diff: FSD vs existing ERD/API + migration plan |
| Consistency Report | Cross-check: ERD ↔ API spec ↔ tasks |
| Discovery Questions | Structured QUESTION_FOR_BA, ASSUMPTION, CONFLICT list for ambiguous FSDs |
| Auth & Security Spec | Auth patterns, role-permission matrix, security requirements |
| Migration Plan | Zero-downtime migration strategy, rollback plan, deployment sequence |
- Generate artifacts — From FSD to full API spec, ERD, UML diagrams, and task cards
- UML diagrams — PlantUML code blocks for PlantUML / PlantText: sequence, class, activity, state, component, and use case diagrams
- Gap analysis — Compare new FSD against existing database schema and API specs
- Consistency checks — Validate alignment across ERD, API spec, and task cards
- Timeline estimation — Story Points (1 SP = 4 hours), developer assignment, dependency tracking, critical path analysis, HTML Gantt chart visualization
- RTM generation — Trace every business requirement to its design solution and test case. One scope = one RTM; the user picks the scope name and which FSD files to trace (a single FSD split into several files is traced together) into a single
output/rtm/RTM_<scope>.md; uncovered requirements stay as empty cells the dashboard highlights - OpenAPI generation — Consolidate
MASTER_SPEC_API.md+output/spec/*.mdinto oneoutput/spec/openapi.yamlwithx-status/x-phase - Discovery mode — Structured questions for ambiguous FSDs before generating specs
- Auth & security — JWT patterns, role-permission matrix, brute force protection, data protection
- Error catalog — Standardized error envelope, error codes, HTTP status mapping
- Frontend tasks — FE-specific cards with component breakdown, API integration, UI states
- Migration planning — Zero-downtime strategy, rollback plan, deployment sequence
- Master files — Rolling
MASTER_ERD.mdandMASTER_SPEC_API.mdfor incremental FSD-by-section work - Project context — Template for tech stack, conventions, environments
- Copy-paste friendly — Markdown tables, fenced
sql/json/plantumlblocks ready for spreadsheets, Jira, Monday, dbdiagram.io, or PlantUML renderers - Optional Python scripts — Validate DBML, check spec structure, extract entity hints, compare artifacts (no external dependencies)
- Optional Streamlit UI — Browser-based interface for the validation scripts
Point your AI assistant to this repo as a skill. For example in OpenCode, add to your project's .agents/skills/ directory or reference the SKILL.md directly.
Copy references/project_context_template.md to your project root as project_context.md and fill in your project details (tech stack, naming conventions, environments, auth patterns).
@project_context.md @fsd_user_management.md — generate spec_api, erd, and tasks
When the FSD is still ambiguous or incomplete:
FSD ini masih draft. List semua pertanyaan dan asumsi — jangan buat spec dulu.
@fsd_draft.md
Analisis FSD ini dan generate ERD, API spec, task cards
@fsd_user_management.md
Generate PlantUML sequence and class diagrams from this FSD. Only UML, no spec.
@fsd_user_management.md
Dokumentasikan auth flow dan role matrix dari FSD ini
@fsd_user_management.md
Generate frontend task cards from this FSD. Include component breakdown, API integration, and acceptance criteria.
@fsd_user_management.md
Compare this new FSD with our existing ERD and API spec. Produce a Gap Report.
@fsd_new_feature.md @erd_current.md @spec_api_current.md
Check consistency between the ERD, API spec, and task cards. List errors and warnings.
@erd.md @spec_api.md @task.md
Assign tasks to developers and generate a visual timeline:
Generate development timeline with Gantt chart from these task cards.
Team: Andi (Senior), Budi (Mid), Citra (Junior)
@task_user_management.md
Or directly from FSD:
Analisis FSD ini, generate task cards dengan story points, lalu buat timeline HTML dengan Gantt chart.
Assign: Andi (Senior), Budi (Mid), Citra (Junior)
@fsd_user_management.md
This generates:
- Task cards with Story Points (1 SP = 4 hours)
- Dependency tracking (Depends On / Blocks)
- Critical path identification
- Developer utilization analysis (no idle devs, no overload)
timeline_<feature>.html— open in browser for interactive Gantt chart
@MASTER_ERD.md @MASTER_SPEC_API.md @fsd_section_3.md — merge changes into master
Trace business requirements down to design solutions and test cases after artifacts exist:
Generate RTM dari FSD dan artifacts yang sudah ada. Output ke output/rtm/RTM.md
This reads input/fsd/*.md, output/spec/*.md, output/erd/*.md (and .dbml), output/task/*.md, plus MASTER_SPEC_API.md / MASTER_ERD.md and produces a single output/rtm/RTM.md (or RTM_<scope>.md when scoped to one FSD/phase) with BR → FR → DS → TC tables. Requirements with no design or test yet keep empty cells — that is the coverage gap.
Consolidate all endpoint specs into one machine-readable file:
Generate openapi.yaml dari semua spec yang ada
Reads MASTER_SPEC_API.md + output/spec/*.md and writes a single valid output/spec/openapi.yaml with summary/description/tags per operation plus x-status: done|in-develop and x-phase where derivable.
| SP | Hours | Criteria |
|---|---|---|
| 1 SP | 4h | Single simple CRUD, no dependency |
| 2 SP | 8h | 1 endpoint + medium logic, or standard FE page |
| 3 SP | 12h | Multi-endpoint, medium logic, light integration |
| 5 SP | 20h | Full feature, multi-table, approval flow |
| 8 SP | 32h | New module, third-party integration, complex |
| 13 SP | 52h | Epic: cross-module, large migration, architecture |
SP per Sprint (2 weeks): Senior ~15 SP, Mid ~10 SP, Junior ~7 SP
fsd-analyzer/
├── SKILL.md # Agent instructions (main skill definition)
├── references/ # Format templates & procedures
│ ├── spec_api_format.md # API spec structure
│ ├── erd_format.md # ERD tables + DBML format
│ ├── uml_format.md # UML diagrams (PlantUML)
│ ├── task_format.md # Developer task cards + Story Points + dependencies
│ ├── gap_analysis.md # Gap analysis procedure + report template
│ ├── consistency_check.md # Consistency check procedure + report template
│ ├── master_artifacts.md # MASTER_ERD + MASTER_SPEC workflow
│ ├── api_conventions.md # API standards (pagination, naming, versioning, sorting)
│ ├── auth_security.md # Auth patterns, role-permission matrix, security
│ ├── error_catalog.md # Error envelope, error codes, HTTP status mapping
│ ├── discovery_questions.md # Discovery mode: structured questions for ambiguous FSD
│ ├── frontend_task_format.md # Frontend task cards (components, API integration, UI states)
│ ├── migration_strategy.md # DB migration plan (zero-downtime, rollback, deployment)
│ ├── project_context_template.md # Project context template (tech stack, conventions)
│ ├── timeline_estimation.md # Timeline + HTML Gantt + SP + dependency + critical path
│ ├── rtm_format.md # Requirement Traceability Matrix (BR → FR → DS → TC)
│ └── openapi_format.md # OpenAPI 3.0 consolidation (x-status / x-phase)
├── scripts/ # Optional local validation (Python, stdlib only)
│ ├── validate_erd.py # DBML table + ref validation
│ ├── validate_spec.py # Spec markdown structure heuristics
│ ├── extract_entities.py # Extract table/entity hints from FSD
│ └── compare_artifacts.py # Compare FSD table mentions vs ERD tables
├── evals/ # Evaluation prompts & sample data
│ ├── evals.json # Test prompts and expected outputs (11 scenarios)
│ ├── sample_fsd.md # Sample Functional Specification Document
│ └── sample_dbml.dbml # Sample DBML for script smoke tests
├── optional_web/ # Streamlit UI for running scripts
│ ├── app.py
│ ├── requirements.txt
│ └── .env.example
└── assets/templates/ # Project-specific snippet placeholders
flowchart TD
FSD[FSD / Requirements] --> DISC{Clear enough?}
DISC -->|No| QUESTIONS[Discovery Questions<br/>QUESTION_FOR_BA / ASSUMPTION]
QUESTIONS --> DISC
DISC -->|Yes| SPEC[Spec API]
SPEC --> ERD[ERD + DBML]
ERD --> UML[UML Diagrams]
SPEC --> TASKS[Task Cards<br/>SP + Dependencies]
TASKS --> FE_TASKS[FE Task Cards]
TASKS --> TIMELINE[Timeline HTML<br/>Gantt Chart]
SPEC --> RTM[RTM<br/>output/rtm/RTM.md]
ERD --> RTM
TASKS --> RTM
ERD --> GAP[Gap Analysis<br/>vs existing artifacts]
GAP --> MIGRATION[Migration Plan]
SPEC --> CONSISTENCY[Consistency Check]
- Discovery — List questions, assumptions (don't generate specs yet)
- Spec API — Define endpoints, auth, validation, errors
- ERD — Design tables, columns, indexes, relationships + DBML
- UML — Generate PlantUML diagrams (sequence, class, activity, etc.)
- Tasks — Create task cards with Story Points and dependencies
- FE Tasks — Frontend-specific cards (if applicable)
- Timeline — Assign developers, generate HTML Gantt chart
- Gap Analysis — Compare against existing system (if applicable)
- Consistency Check — Validate all artifacts aligned
- RTM — Trace BR → FR → DS → TC into
output/rtm/RTM.md/RTM_<scope>.md - OpenAPI — Consolidate specs into
output/spec/openapi.yaml
All scripts use Python standard library only (no pip install needed for the scripts themselves).
# Extract entity/table hints from an FSD
python scripts/extract_entities.py path/to/fsd.md
# Validate DBML structure (tables + foreign key refs)
python scripts/validate_erd.py path/to/schema.dbml
# Check API spec markdown structure
python scripts/validate_spec.py path/to/spec_api.md
# Compare FSD table mentions vs ERD tables (heuristic)
python scripts/compare_artifacts.py --fsd path/to/fsd.md --erd path/to/erd.mdpython scripts/extract_entities.py evals/sample_fsd.md
python scripts/validate_erd.py evals/sample_dbml.dbmlA minimal Streamlit interface to paste FSD/spec/DBML text and run validators in the browser.
cd optional_web
pip install -r requirements.txt
streamlit run app.pyFor projects where you work FSD-by-section (common in large systems):
- Create
MASTER_ERD.mdandMASTER_SPEC_API.mdin your project root - For each FSD section,
@-reference the master files + the new FSD slice - The agent merges changes into the master files incrementally
- No need to re-attach every legacy file each time
See references/master_artifacts.md for the full workflow.
Create project_context.md once per project so the agent has consistent conventions:
- Copy template from
references/project_context_template.mdto project root - Fill in tech stack, naming conventions, environments, auth patterns
@-reference it in every prompt alongside FSD
Every output is checked against:
- All FSD requirements covered or explicitly flagged
- REST consistency with auth and error documentation
- API conventions followed (pagination, naming, versioning)
- Error codes follow standard catalog
- Auth pattern and role-permission matrix documented
- Normalized schema with justified FKs and indexes
- Cross-artifact alignment (spec ↔ ERD ↔ tasks ↔ UML)
- UML diagram entity names, endpoint paths, and statuses consistent with ERD and spec
- Developer-ready task granularity with QA acceptance criteria
- All tasks have Story Points and dependency fields
- Timeline HTML with balanced developer utilization
- Critical path identified and risks flagged
sql/json/plantumlcode fences for easy copy-paste
Works with any AI coding assistant that supports custom skill instructions:
- Cursor
- Claude Code
- OpenCode
- Any agent that can read
SKILL.mdas context
Untuk workflow lengkap dari Monday.com board export ke Technical Documentation (DOCX), gunakan skill companion monday-td-generator yang tersedia di .agents/skills/monday-td-generator/.
Skill otomatis yang mengubah export board Monday.com menjadi Technical Documentation profesional dengan:
- Parse Excel Export - Baca file
.xlsxdari Monday.com, extract items & subitems dengan status DONE/GO-LIVE - Enrich dari Updates - Parse detail API (request/response body, flow logic) dari updates di setiap subitem
- Generate Technical Documentation - Hasilkan TD lengkap dengan:
- Modul terpisah (Authentication, Management, API endpoints, dll)
- Front End & Back End specifications
- Detail API endpoints dengan 2-column table format
- Request/Response body dan flow logic dari updates
- Mermaid diagrams (system architecture + ERD)
- Export ke DOCX - Convert ke Word document dengan template Onesist profesional
Cukup jalankan script utama dengan file export Monday:
python3 .agents/skills/monday-td-generator/scripts/generate_td.py \
--excel path/to/monday-export.xlsx \
--output technical-documentation.mdScript akan:
- Setup environment otomatis (install dependencies jika belum ada)
- Parse Excel dan filter items DONE
- Enrich dengan updates
- Generate Technical Documentation
- Export ke DOCX dengan mermaid diagrams
Untuk kontrol lebih detail, jalankan setiap step terpisah:
Step 1: Setup Environment
python3 .agents/skills/monday-td-generator/scripts/setup_env.pyStep 2: Parse Monday Export
python3 .agents/skills/monday-td-generator/scripts/parse_monday.py \
path/to/monday-export.xlsx \
--output parsed.jsonStep 3: Enrich dengan Updates
python3 .agents/skills/monday-td-generator/scripts/parse_updates.py \
parsed.json \
enriched.jsonStep 4: Generate Technical Documentation
python3 .agents/skills/monday-td-generator/scripts/generate_td.py \
enriched.json \
technical-documentation.mdStep 5: Export ke DOCX (Optional)
python3 .agents/skills/monday-td-generator/scripts/export_docx.py \
technical-documentation.md \
--output technical-documentation.docx.agents/skills/monday-td-generator/
├── SKILL.md # Definisi skill
├── templates/
│ └── technical-documentation.md # Template markdown
├── references/
│ ├── generation-prompt.md # Prompt untuk generate TD
│ └── monday-format-guide.md # Dokumentasi format Monday
└── scripts/
├── setup_env.py # Setup environment (Python + dependencies)
├── parse_monday.py # Parse Excel → JSON
├── parse_updates.py # Parse API details dari updates
├── generate_td.py # Generate TD dari enriched JSON
└── export_docx.py # Export ke DOCX dengan mermaid rendering
Export single phase:
python3 .agents/skills/monday-td-generator/scripts/generate_td.py \
--excel PRJ_Teman_SEVA_ACC_Phase_1_0.xlsx \
--output td-phase-1.mdExport multiple phases:
# Parse semua phase
python3 .agents/skills/monday-td-generator/scripts/parse_monday.py \
PRJ_Teman_SEVA_ACC_Phase_1_0.xlsx \
PRJ_Teman_SEVA_ACC_Phase_2_0.xlsx \
PRJ_Teman_SEVA_ACC_Phase_3_0_MVP_1_0.xlsx \
--output all-phases.json
# Enrich dan generate
python3 .agents/skills/monday-td-generator/scripts/parse_updates.py all-phases.json all-phases-enriched.json
python3 .agents/skills/monday-td-generator/scripts/generate_td.py all-phases-enriched.json td-complete.md
python3 .agents/skills/monday-td-generator/scripts/export_docx.py td-complete.md --output td-complete.docxBerikut adalah contoh-contoh prompt yang bisa Anda gunakan saat berinteraksi dengan AI assistant (Cursor, Claude Code, dll) untuk menjalankan skill monday-td-generator:
Tolong buatkan Technical Documentation dari export Monday ini:
@monday-export.xlsx
Generate dokumen lengkap dengan:
- Parse Excel dan filter items DONE/GO-LIVE
- Enrich dengan request/response dari updates
- Generate TD dalam format markdown
- Export ke DOCX dengan mermaid diagrams
Saya punya 3 file export Monday untuk project ini:
- @board-phase-1.xlsx
- @board-phase-2.xlsx
- @board-phase-3.xlsx
Tolong generate Technical Documentation yang menggabungkan semua phase menjadi satu dokumen lengkap.
Generate Technical Documentation dari @monday-export.xlsx dengan metadata berikut:
- Project Name: My Project
- Customer: Client Company
- Version: 1.0.0
- Author: System Analyst Team
- Date: 2026-01-15
Pastikan metadata ini muncul di cover page dan header/footer DOCX.
Parse file @board-export.xlsx dan extract semua API details dari updates.
Saya hanya butuh JSON enriched-nya saja, belum perlu generate TD.
Simpan hasilnya di api-details.json
Saya sudah punya enriched JSON di @enriched-data.json.
Tolong generate Technical Documentation markdown dari data tersebut.
Gunakan template dari .agents/skills/monday-td-generator/templates/technical-documentation.md
Saya sudah punya Technical Documentation di @td-output.md.
Tolong convert ke DOCX dengan:
- Template Onesist (header/footer profesional)
- Render semua mermaid diagrams sebagai PNG
- Output: td-output.docx
Dari file @all-phases.xlsx, saya hanya mau generate Technical Documentation untuk:
- Phase 2 items saja
- Filter status: DONE dan GO-LIVE
- Output: td-phase-2.md dan td-phase-2.docx
Saya mau pakai skill monday-td-generator tapi belum yakin dependencies-nya lengkap.
Tolong jalankan setup_env.py untuk memastikan:
- Python 3.8+ terinstall
- openpyxl, python-docx, mmdc tersedia
- Semua dependencies siap digunakan
Parse file @monday-export.xlsx dan tampilkan summary:
- Berapa total items dan subitems?
- Berapa items dengan status DONE/GO-LIVE?
- Berapa API endpoints yang terdeteksi dari updates?
- Berapa subitems yang punya updates dengan request/response details?
Jangan generate TD dulu, saya mau review datanya terlebih dahulu.
Generate Technical Documentation dari @board.xlsx tapi gunakan filter status berikut:
- DONE
- GO-LIVE
- COMPLETED
- RELEASED
- DEPLOYED
Jangan filter "In Progress" atau "Testing", hanya yang sudah benar-benar selesai.
Saya sudah punya @td-existing.md dari generate sebelumnya.
Sekarang ada update di board, ini file barunya: @monday-export-updated.xlsx
Tolong:
1. Parse file baru
2. Bandingkan dengan TD yang sudah ada
3. Regenerate TD dengan data terbaru
4. Highlight section yang berubah (added/modified/removed)
Dari @enriched-data.json, saya hanya mau generate Technical Documentation untuk modul:
- Authentication & Login
- User Management
- Payment Processing
Skip modul lainnya. Output: td-auth-user-payment.md
- Selalu attach file Excel menggunakan
@filename.xlsxagar AI assistant bisa mengaksesnya - Sebutkan output yang diinginkan (markdown saja, DOCX saja, atau keduanya)
- Spesifikasikan filter jika tidak ingin menggunakan default (DONE/GO-LIVE)
- Berikan metadata jika ingin customize cover page dan header
- Minta summary dulu sebelum generate full TD untuk review data
- Gunakan path lengkap untuk file input/output jika working directory tidak jelas
Skill ini membutuhkan:
- Python 3.8+
- openpyxl (parse Excel)
- python-docx (generate DOCX)
- mmdc (mermaid-cli untuk render diagrams)
Semua dependencies akan di-install otomatis oleh setup_env.py.
Markdown (td-*.md):
- Cover page dengan metadata
- Approvals & Knowledge section
- Introduction (Purpose, Background, Objectives)
- Project Scope (In Scope & Out of Scope)
- Effort Estimation (Story Points breakdown)
- System Overview (Architecture diagram)
- 17 Modul Detail (Authentication, TSL Management, Agent Management, dll)
- Front End & Back End specifications
- API endpoints dengan request/response
- Flow logic detail
- Lampiran ERD (Mermaid diagram)
- Data Specification (table schemas)
DOCX (td-*.docx):
- Template Onesist profesional
- Header/footer dengan metadata
- Mermaid diagrams di-render sebagai PNG
- Formatting konsisten dengan fsd-analyzer output
MIT — use freely in your software projects.