firefrost-operations-manual/docs/standards/FFG-STD-005-implementation-guide-standard.md

FFG-STD-005: Implementation Guide Standard

Version: 1.0
Effective Date: April 5, 2026
Author: Michael (The Wizard) + Claude (Chronicler #61)
Status: ACTIVE

---

1. Purpose

This standard defines the required structure and content for Implementation Guides — comprehensive documents that enable any AI or developer to implement a project from cold start without prior context.

Core Principle: If Claude crashes mid-project, another AI (Gemini, GPT-4o, or a new Claude session) must be able to pick up the work using only the Implementation Guide.

---

2. When to Create

Trigger	Action
New major feature (10+ hours estimated)	Create guide BEFORE building
New system/service	Create guide BEFORE building
Architectural rewrite	Create guide BEFORE building
External consultation (e.g., Gemini)	Consolidate into guide AFTER consultation, BEFORE building
Complex integration	Create guide BEFORE building

Rule: No major implementation begins without an Implementation Guide committed to the ops manual.

---

3. Required Sections

Every Implementation Guide MUST contain these sections:

3.1 Header Block

# [Project Name] — Complete Implementation Guide

**Version:** [X.Y]  
**Created:** [Date]  
**Authors:** [Names and roles]  
**Purpose:** Cold-start handoff document — any AI or developer can implement [project] from this single document.

3.2 Table of Contents

Numbered list of all sections with anchor links.

3.3 Project Overview

• What is this project?
• Who are the users?
• Key characteristics (stack, auth, design, etc.)
• Brand/design requirements (if applicable)

3.4 Architecture Decisions

• Key decisions made and WHY
• Options considered and rejected
• Constraints and requirements
• Dependencies on other systems

3.5 Complete File Structure

/path/to/project/
├── folder/
│   ├── file.js         # Description
│   └── another.js      # Description
└── ...

Every file that will be created must be listed.

3.6 Database Schema (if applicable)

• All tables with full CREATE statements
• Indexes
• Seed data
• Migration order and dependencies

3.7 All Code

Every code file, organized by path, copy-paste ready.

Format:

### `path/to/file.js`

\`\`\`javascript
// Complete code here
\`\`\`

No partial snippets. Every file must be complete and functional.

3.8 Configuration Files

• Environment variables template (.env.example)
• Config files (nginx, PM2, systemd, etc.)
• Third-party service setup (Cloudflare, Stripe, Discord, etc.)

3.9 Deployment Infrastructure

• Server information (IPs, roles)
• DNS setup
• SSL/TLS configuration
• Firewall rules
• Service management (PM2, systemd)
• Bootstrap scripts

3.10 Implementation Checklist

Phased checklist with checkboxes:

### Phase 1: [Name]

- [ ] Task 1
- [ ] Task 2
- [ ] Task 3

### Phase 2: [Name]

- [ ] Task 4
- [ ] Task 5

3.11 Migration/Integration (if applicable)

• How existing systems are affected
• Data migration steps
• Rollback procedures
• Strangler Fig patterns (if replacing existing functionality)

3.12 Emergency Contacts

Who/what can continue this work if the primary implementer is unavailable:

## Emergency Contacts

If [primary] is unavailable:

1. **[Backup 1]** — [Why they can help]
2. **[Backup 2]** — [Why they can help]
3. **New session** — Start fresh with this document

3.13 Document History

Version	Date	Author	Changes
1.0	YYYY-MM-DD	Name	Initial creation

---

4. Optional Sections

Include when relevant:

Section	When to Include
API Documentation	External-facing APIs
Testing Strategy	Complex business logic
Performance Considerations	High-traffic or resource-intensive
Security Considerations	Auth, sensitive data, external access
Monitoring & Alerting	Production services
Troubleshooting Guide	Complex deployments

---

5. Quality Requirements

5.1 Completeness

• Any file referenced in the structure section has complete code provided
• All configuration values are documented (even if secrets are placeholders)
• All external dependencies are listed with versions
• All third-party setup steps are documented

5.2 Copy-Paste Ready

• Code blocks can be copied directly into files
• Commands can be run as-is (no placeholder substitution needed except secrets)
• File paths are absolute or clearly relative to project root

5.3 Context-Free

• Document makes sense without reading any other document
• No references to "as discussed earlier" or "see previous session"
• All decisions include rationale (not just "we decided X")

5.4 Actionable

• Implementation checklist covers every step
• Phases are logical and sequential
• Dependencies between steps are clear

---

6. File Location

Implementation Guides are stored in:

docs/implementation/[project-name]-implementation-guide.md

Examples:

• docs/implementation/trinity-console-2-implementation-guide.md
• docs/implementation/trinity-codex-implementation-guide.md
• docs/implementation/arbiter-lifecycle-handlers-implementation-guide.md

---

7. Relationship to Other Documents

Document Type	Relationship
Consultation Docs	Consolidated INTO implementation guide
Task Documentation	References implementation guide
Session Handoffs	References implementation guide for context
Architecture Docs	May be extracted FROM implementation guide

The Implementation Guide is the single source of truth for building the project.

---

8. Maintenance

8.1 During Implementation

Update the guide as changes are made:

• Code changes → Update code sections
• Architecture changes → Update decisions section
• New files → Update file structure

8.2 After Implementation

• Mark as IMPLEMENTED in header
• Add "Lessons Learned" section if significant
• Archive consultation docs (keep for reference, but guide is primary)

8.3 Version Increments

Change Type	Version Bump
Typo fixes	No change
Clarifications	Patch (1.0 → 1.0.1)
New sections	Minor (1.0 → 1.1)
Major restructure	Major (1.0 → 2.0)

---

9. Template

A starter template is available at:

docs/templates/implementation-guide-template.md

---

10. Examples

Project	Guide Location	Quality
Trinity Console 2.0	docs/implementation/trinity-console-2-implementation-guide.md	Reference implementation

---

11. Enforcement

• Chroniclers: Must create implementation guide before major work begins
• Michael: Reviews guides before implementation starts
• Gemini: May be consulted for architecture, output consolidated into guide

No exceptions. Small fixes don't need guides. Major features do.

---

12. Rationale

This standard exists because:

1. AI sessions are ephemeral — Context is lost between sessions
2. Consultation is scattered — 7 Gemini rounds = 7 files = confusion
3. Documentation debt is real — "I'll document it later" means never
4. Handoff must be instant — No "let me catch you up" delays
5. The Trinity needs independence — Michael, Meg, Holly can hand work to any AI

The 30 minutes spent writing a guide saves 3 hours of reconstruction later.

---

Fire + Frost + Foundation = Where Love Builds Legacy 💙🔥❄️