Skip to main content

​
Playbook Structure Standardization

​
Overview

Playbook Structure Standardization ensures every playbook you build meets Fiftyknots quality standards before it goes live. The validation system checks your work against the 8-phase framework, catches missing components, and flags brand compliance issues - so you ship playbooks that work the first time. Whether you’re a developer building for the marketplace or a consultant creating internal frameworks, standardization removes guesswork and proves your playbook is production-ready.

​
Step-by-Step Guide

​
For Developers Validating Locally

  1. Install the validation tool - Run npm install -g @fiftyknots/playbook-validator in your terminal to get the command-line validator.
  2. Run validation on your playbook file - Navigate to your project directory and run npx validate-playbook venture-studio.json. The validator checks all 8 required phases (PRD, Service Blueprint, Component Specs, OST, Runbook, FRS/TRS, SLA Definitions, War Stories).
  3. Review the validation report - You’ll see either a green “Validation passed” message with a component summary, or red error messages showing exactly which fields are missing (with file path and line number). Warnings appear in yellow for optional fields.
  4. Fix any errors - If you see errors like “Missing required field ‘serviceBlueprint’”, add that phase to your JSON. For warnings like “Component ‘idea-validation-sprint’ missing field ‘slas’”, decide if you want to add the optional content.
  5. Generate a compliance report - Run npx validate-playbook --output report.html to create a detailed HTML report showing your compliance score, missing optional fields, and improvement suggestions. Share this with stakeholders or keep it for your records.
  6. Check brand compliance - Run validation with the --strict flag to verify colors match the Fiftyknots palette. The validator checks hex codes and allows ±5% color variance (HSL comparison) for practical compliance.

​
For Developers Submitting to Marketplace

  1. Prepare your validated playbook - Make sure local validation passes with no errors. Warnings are acceptable but will be flagged for admin review.
  2. Submit via API - POST your playbook JSON to /api/v1/marketplace/developers/:id/playbooks. The platform automatically runs validation on submission.
  3. Check submission status - If validation passes, you’ll receive a 201 response and your submission enters the queue with a “Passed Automated Validation” label. If validation fails, you’ll get a 400 response with detailed error messages in JSON format.
  4. Review admin feedback - Admins see your validation status in the submission queue. Playbooks with warnings get flagged for manual review. Check your developer dashboard for any feedback or requests for changes.
  5. Resubmit if needed - If you need to update your playbook, use PATCH to edit. Validation runs again automatically, and version history tracks the change (e.g., “v1.1 - Validation: Passed → Failed due to missing OST”).

​
For Developers Completing Creator’s Playbook

  1. Receive Creator’s Playbook access - When you register as a new developer, you automatically get free access to the “Playbook Creator’s Playbook” with a welcome email explaining the onboarding process.
  2. Work through Phases 1-3 - Complete the PRD, Service Blueprint, and Component Specs phases. These aren’t just tutorials - you’re building your actual application materials.
  3. Submit for review - At the “Submit Phase 1-3 for Review” step, upload your completed artifacts. Admins review your actual work (not portfolio screenshots) to assess your methodology understanding.
  4. Get approved and unlock remaining phases - Once admins approve your Phase 1-3 work, you receive an approval email, gain access to Phases 4-8, and your developer account activates with platformApproved: true.
  5. Complete all 8 phases and get certified - Finish the remaining phases to earn your “Certified Playbook Creator” badge on your developer profile. You’ll also get preferential placement in marketplace search results.

​
For Consultants Purchasing Creator’s Playbook

  1. Find Creator’s Playbook in marketplace - Search for “playbook creation” or filter by “Operations” category. You’ll see the playbook priced at $497 one-time (free for approved developers).
  2. Purchase and access content - Complete payment to receive immediate access to all 8 phases plus downloadable templates (PRD template, Service Blueprint canvas, etc.).
  3. Build your playbook - Work through each phase at your own pace. After completing each phase, download your work as Word docs or structured JSON for version control.
  4. Consider upgrade options - If you want hands-on help, the playbook detail page shows an “Upgrade to Done-For-You ($2,997)” option where Fiftyknots co-creates your first playbook with you.
  5. Export and share - Once complete, export a “Playbook Development Package” ZIP containing all 8 artifacts plus a generated web presentation JSON ready for any use.

​
For Developers Converting Word Documents

  1. Access the conversion tool - Navigate to /tools/word-to-json (or use the Playbook IDE page at /playbookide).
  2. Upload your Word document - Start with a single document (like your PRD) to test the conversion. The tool extracts content and maps it to JSON fields (scope → prd.scope, users → prd.targetUsers, etc.).
  3. Review confidence scores - The conversion tool shows confidence scores per field (e.g., “scope: 95% confident”, “outcomes: 60% confident - please review”). Check low-confidence extractions carefully.
  4. Bulk upload all documents - Upload all 8 Word documents at once. The tool combines them into a single playbook-development.json file and runs validation automatically.
  5. Fix validation errors - If conversion produces validation errors, you’ll see a side-by-side view: Word doc (left), extracted JSON (right), and validation errors (bottom) with “Fix” buttons. Correct errors and re-export.
  6. Export both formats - Once successful, you receive both development artifact JSON (for version control) and web presentation JSON (ready for marketplace submission).

​
Common Questions

Q: What happens if my playbook is missing optional fields? A: The validator passes your playbook but generates warnings like “Optional field ‘warStory’ missing in 3 of 5 steps” and shows a completeness score (e.g., “87% complete (13 optional fields missing)”). You can submit to the marketplace, but admins may ask you to add optional content before approval. Optional fields improve quality but aren’t blockers. Q: Can I use custom ICPs that aren’t in the standard list? A: No - validation rejects custom ICPs with an error: “Invalid ICP. Must be one of: [list]. To propose new ICP, contact support@fiftyknots.com.” However, admins can manually approve custom ICPs, which get added to the enum in the next schema version (v2.x). If you have a strong business case for a new ICP, reach out to support before building. Q: What if I need more than 20 component specs? A: The schema enforces minItems: 11, maxItems: 20 for component specs. Playbooks with extra components pass validation but get flagged for admin review with a message like “Non-standard component detected: ‘blockchain-setup’”. Admins evaluate whether the extra complexity is justified. Most playbooks fit within 11-20 components - if yours doesn’t, you may be overcomplicating or building multiple playbooks. Q: Do I need to use exact Fiftyknots brand colors? A: The validator normalizes hex codes to uppercase and allows ±5% color variance (HSL comparison) for practical compliance. You don’t need pixel-perfect matches. However, using --strict flag requires exact palette matches. The approved palette includes colors like #3A74F5, #FFD336, and others. Check the brand guidelines in your developer portal. Q: How does similarity checking work for marketplace submissions? A: The platform runs a similarity check against existing marketplace playbooks. If >70% text similarity is detected, your submission gets flagged for admin review. If >90% similarity, the system auto-rejects with “Duplicate content detected. Please create original content or contact support if this is a collaboration.” This protects against plagiarism but allows legitimate collaborations if you coordinate with support first. Q: Can I submit a playbook that’s still in development? A: No - validation enforces that all prerequisite phases are complete. You can’t submit Phase 8 without completing Phases 1-7. The validator rejects with “Cannot submit Phase 8 without completing Phases 1-7. Missing: [list].” Use the draft system in the Playbook IDE (/playbookide) to save work in progress, then validate and submit only when complete.

​
Troubleshooting

Problem: Validation fails with “Missing required field” errors Solution: Check that your JSON includes all 8 required phases: PRD, Service Blueprint, Component Specs, OST, Runbook, FRS/TRS, SLA Definitions, and War Stories. The error message shows the exact field name and file path. Add the missing phase to your JSON structure. If you’re converting from Word docs, make sure you uploaded documents for all 8 phases. Problem: Brand compliance fails even though I’m using Fiftyknots colors Solution: Hex codes are case-sensitive before normalization. Try converting your colors to uppercase (e.g., #3a74f5 → #3A74F5). If you’re using slight color variations, run validation without the --strict flag - the standard mode allows ±5% HSL variance. If colors still fail, compare against the approved palette in your developer portal and adjust. Problem: Conversion tool shows low confidence scores on extracted fields Solution: Low confidence (below 70%) means the AI couldn’t clearly map your Word doc content to JSON fields. This happens when documents lack clear structure or use non-standard headings. Review the side-by-side view and manually correct the extracted JSON. For future conversions, use the provided templates (downloadable from Creator’s Playbook) which have optimal structure for conversion. Problem: My runbook validation fails with “must span 4 weeks (20 business days)” error Solution: The validator enforces a 4-week minimum runbook duration (20 business days). If your runbook shows 15 days, either extend the timeline or add a justification in the comments field. Admins can override this requirement if you have a valid reason for a shorter runbook (e.g., rapid prototyping playbooks). Submit with the justification and let admins review. Playbook IDE - The visual editor at /playbookide lets you build playbooks with real-time validation as you work. It’s the easiest way to create playbooks from scratch without writing JSON by hand. The IDE integrates with the same validation engine, so you catch errors before exporting. Developer Dashboard - Track your marketplace submissions, validation history, and earnings at /developerdashboard. See which playbooks passed validation, which need revisions, and monitor your certification progress if you’re completing Creator’s Playbook. Marketplace Analytics - Once your playbook is published, use /playbookanalytics to see downloads, ratings, and revenue. Validation scores correlate with marketplace performance - higher compliance scores (95%+) drive better search placement and more downloads.