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

```markdown
# [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:
```markdown
### `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:

```markdown
### 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:

```markdown
## 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** 💙🔥❄️