Skip to main content

​
Playbook Structure Standardization

​
1. Overview

Build playbooks that meet marketplace standards from day one. The validation system checks your work against the 8-phase Fiftyknots structure before submission - catching missing components, brand misalignments, and structural gaps. You ship faster when you validate early, and the platform auto-rejects broken submissions so admins only review quality work.

​
2. Step-by-Step Guide

Local Validation (For Developers)
  1. Create your playbook JSON - Build your file with all 8 required phases: PRD, Service Blueprint, Component Specs, OST, Implementation Runbook, War Stories, Pricing Model, and Success Metrics.
  2. Run the validator - Open your terminal and run npx validate-playbook your-playbook-name.json. The tool scans your file against Fiftyknots standards.
  3. Review validation results - Pass: You see ”✅ Validation passed! Your playbook meets FiftyKnots standards” with a component summary. Fail: You see specific errors with file paths and line numbers (e.g., ”❌ Validation failed: Missing required field ‘serviceBlueprint’”).
  4. Fix flagged issues - Address errors (missing phases, invalid ICPs, brand color mismatches). Warnings won’t block submission but lower your completeness score.
  5. Generate compliance report - Run npx validate-playbook --output report.html to get a detailed HTML report showing compliance score, missing optional fields, and improvement suggestions.
Platform Submission (For Developers)
  1. Submit via API - POST your validated playbook to /api/v1/marketplace/developers/:id/playbooks. Valid submissions return 201 status and “Passed Automated Validation” label.
  2. Check submission status - Navigate to Developer Dashboard (/developerdashboard) to see validation status: ✅ Passed, ⚠️ Warnings, or ❌ Failed.
  3. Handle rejections - Failed submissions return 400 with JSON error details. Fix issues locally, revalidate, and resubmit. Updates trigger fresh validation automatically.
  4. Admin review - Passed submissions enter the admin queue. Admins see your validation status and can filter by state in Admin Playbook Review (/admin/adminplaybookreview).
Creator’s Playbook Onboarding (For New Developers)
  1. Register as developer - Complete registration at Developer Onboarding (/developeronboarding). You receive immediate free access to “Playbook Creator’s Playbook” via email.
  2. Complete Phases 1-3 - Work through PRD, Service Blueprint, and Component Specs modules. Upload your completed artifacts when you reach “Submit Phase 1-3 for Review.”
  3. Await approval - Admins review your actual work (not portfolio screenshots). Approved work unlocks Phases 4-8 AND activates your developer account with platformApproved: true.
  4. Finish all 8 phases - Complete the remaining phases to earn your “Certified Playbook Creator” badge and preferential search placement.
  5. Publish your first playbook - Use your certified work as the foundation for marketplace submissions.
Creator’s Playbook Purchase (For Consultants)
  1. Find the playbook - Search “playbook creation” in Marketplace (/marketplace) or filter by category “Operations.” Price: $497 one-time (free for approved developers).
  2. Purchase and access - Complete payment to unlock all 8 phases immediately with downloadable templates (PRD template, Service Blueprint canvas, etc.).
  3. Export your work - Download completed phases as Word docs OR structured JSON for version control. Generate a “Playbook Development Package” ZIP containing all 8 artifacts plus web presentation JSON.
  4. Upgrade option - View “Upgrade to Done-For-You ($2,997)” on the detail page to have Fiftyknots co-create your first playbook.
Word Document Conversion (For Developers)
  1. Upload Word docs - Navigate to /tools/word-to-json and upload your PRD Word document. The tool extracts content into structured JSON fields.
  2. Review confidence scores - Check extraction accuracy. High confidence (95%): Auto-accepted. Low confidence (60%): Flagged for manual review.
  3. Fix extraction errors - Use the side-by-side view: Word doc (left), extracted JSON (right), validation errors (bottom). Click “Fix” buttons to correct issues.
  4. Bulk convert - Upload all 8 Word documents at once. The tool combines them into a single playbook-development.json and validates against schema.
  5. Export final files - Receive both development artifact JSON AND marketplace-ready web presentation JSON.

​
3. Common Questions

Q: What happens if I submit a playbook without all 8 phases?
A: Validation rejects it immediately with error “Cannot submit Phase 8 without completing Phases 1-7. Missing: [list].” You receive a 400 status and must complete all prerequisite phases before resubmission. Q: Can I use custom ICPs not in the standard list?
A: No. Validation rejects custom ICPs with “Invalid ICP. Must be one of: [list]. To propose new ICP, contact support@fiftyknots.com.” Admins can manually approve custom ICPs for schema v2.x updates. Q: My brand colors are close but not exact matches. Will validation fail?
A: Running with --strict flag fails on color mismatches. Standard validation allows ±5% HSL variance for practical compliance. Normalized hex codes (uppercase) are compared against approved palette. Q: How does the platform detect duplicate content?
A: Validation runs similarity checks against existing marketplace playbooks. 70%+ similarity triggers admin review warning. 90%+ similarity auto-rejects with “Duplicate content detected. Please create original content or contact support if this is a collaboration.” Q: Do I need to complete Creator’s Playbook to publish on the marketplace?
A: No, but it helps. Completing all 8 phases earns you “Certified Playbook Creator” badge and preferential search placement. You can submit without certification, but approved developers get priority.

​
4. Troubleshooting

Issue: Validation shows “Missing required field ‘slas’” for Component Specs
Solution: SLAs are optional but recommended. This warning doesn’t block submission - your completeness score drops to show 87% complete (13 optional fields missing). Add SLA definitions to improve score and admin review confidence. Issue: Runbook validation fails with “Runbook must span 4 weeks (20 business days). Found: 15 days”
Solution: Extend your runbook timeline to 20 business days OR document justification in the comments field for admin override. Admins can approve shorter timelines with valid business reasoning. Issue: Word-to-JSON extraction shows low confidence scores for multiple fields
Solution: Low confidence (below 60%) means the AI couldn’t parse your document structure reliably. Use the side-by-side editor to manually correct extracted fields. Better yet: structure your Word docs with clear section headers matching the PRD template for higher accuracy. Issue: Platform accepts my submission but flags it “Has Warnings”
Solution: Warnings don’t block publication but signal quality gaps. Common warnings: missing war stories, incomplete optional fields, or extra non-standard components. Review the warning list, address critical items, and PATCH your submission to trigger re-validation. Playbook IDE (/playbookide) - Build and edit your playbook in a visual editor with real-time validation feedback. Connects directly to the validation API so you see errors as you type instead of after submission. Developer Analytics (/developeranalytics) - Track validation pass rates, submission trends, and revenue from published playbooks. See which validation errors block most submissions so you avoid common pitfalls. Admin Playbook Review (/admin/adminplaybookreview) - Admin view showing pending submissions filtered by validation state. Admins review your passed submissions faster because structural issues are already caught.