firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: FFG-STD-005 Implementation Guide Standard + Template

Browse Source 
New standard establishing documentation requirements for major projects.

FFG-STD-005 defines:
- When to create implementation guides (BEFORE building)
- Required sections (13 mandatory, 6 optional)
- Quality requirements (completeness, copy-paste ready, context-free)
- File location conventions
- Maintenance procedures
- Enforcement rules

Core principle: If Claude crashes, another AI must be able to
continue using only the implementation guide.

Template provided at docs/templates/implementation-guide-template.md

Reference implementation: Trinity Console 2.0 guide (1,776 lines)

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

Signed-off-by: Claude (Chronicler #61) <claude@firefrostgaming.com>
This commit is contained in:
Claude (Chronicler #61)
2026-04-05 12:19:27 +00:00
parent ae55b7d1e2
commit 4e416c2996
2 changed files with 623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
docs/standards/FFG-STD-005-implementation-guide-standard.md Normal file
View File

@@ -0,0 +1,300 @@
# 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** 💙🔥❄️

323
docs/templates/implementation-guide-template.md vendored Normal file
View File

@@ -0,0 +1,323 @@
# [Project Name] — Complete Implementation Guide
**Version:** 1.0
**Created:** [Date]
**Authors:** [Names and roles]
**Purpose:** Cold-start handoff document — any AI or developer can implement [project] from this single document.
---
## Table of Contents
1. [Project Overview](#1-project-overview)
2. [Architecture Decisions](#2-architecture-decisions)
3. [Complete File Structure](#3-complete-file-structure)
4. [Database Schema](#4-database-schema)
5. [All Code](#5-all-code)
6. [Configuration Files](#6-configuration-files)
7. [Deployment Infrastructure](#7-deployment-infrastructure)
8. [Implementation Checklist](#8-implementation-checklist)
9. [Migration/Integration](#9-migrationintegration)
10. [Emergency Contacts](#10-emergency-contacts)
11. [Document History](#11-document-history)
---
## 1. Project Overview
### What is This Project?
[1-2 paragraphs describing the project purpose]
### Users
| Name/Role | Description | Access Level |
|-----------|-------------|--------------|
| [User 1] | [Description] | [Access] |
| [User 2] | [Description] | [Access] |
### Key Characteristics
- **Stack:** [Technologies used]
- **Auth:** [Authentication method]
- **Design:** [Design requirements/theme]
- **Deployment:** [Where it lives]
### Brand/Design Requirements (if applicable)
| Element | Value | Usage |
|---------|-------|-------|
| [Color 1] | `#HEXCODE` | [Usage] |
| [Color 2] | `#HEXCODE` | [Usage] |
---
## 2. Architecture Decisions
### Decision 1: [Title]
**Options Considered:**
1. [Option A] — [Pros/Cons]
2. [Option B] — [Pros/Cons]
**Decision:** [What was chosen]
**Rationale:** [Why this option]
### Decision 2: [Title]
[Repeat pattern]
### Constraints & Requirements
- [Constraint 1]
- [Constraint 2]
### Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| [Package] | [Version] | [Why needed] |
---
## 3. Complete File Structure
```
/path/to/project/
├── folder/
│ ├── file.js # [Description]
│ └── another.js # [Description]
├── config/
│ └── settings.json # [Description]
└── README.md # [Description]
```
---
## 4. Database Schema
### Migration Order
1. `001_[name].sql` — [Description]
2. `002_[name].sql` — [Description]
### `migrations/001_[name].sql`
```sql
-- Description of what this migration does
CREATE TABLE IF NOT EXISTS table_name (
id SERIAL PRIMARY KEY,
column_name VARCHAR(100) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Indexes
CREATE INDEX IF NOT EXISTS idx_name ON table_name(column_name);
-- Seed data (if any)
INSERT INTO table_name (column_name) VALUES
('value1'),
('value2')
ON CONFLICT DO NOTHING;
```
### `migrations/002_[name].sql`
```sql
-- [Continue pattern]
```
---
## 5. All Code
### `src/index.js`
```javascript
// Main entry point
// [Complete code here]
```
### `src/module/file.js`
```javascript
// [Complete code here]
```
### `src/views/template.ejs`
```html
<!-- [Complete code here] -->
```
[Continue for ALL files in the structure]
---
## 6. Configuration Files
### Environment Variables (`.env`)
```env
# Database
DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=
# Authentication
AUTH_SECRET=
# External Services
SERVICE_API_KEY=
# Application
PORT=3000
NODE_ENV=production
BASE_URL=https://example.com
```
### PM2 Configuration (`ecosystem.config.js`)
```javascript
module.exports = {
apps: [{
name: "app-name",
script: "./src/index.js",
watch: false,
env: {
NODE_ENV: "production",
PORT: 3000
}
}]
};
```
### Nginx Configuration
```nginx
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
---
## 7. Deployment Infrastructure
### Server Information
| Server | IP | Role |
|--------|-----|------|
| [Server 1] | [IP] | [Role] |
| [Server 2] | [IP] | [Role] |
### DNS Setup
| Record | Type | Value |
|--------|------|-------|
| [subdomain] | A | [IP] |
### Bootstrap Script
```bash
# System updates
sudo apt update && sudo apt upgrade -y
# Install dependencies
sudo apt install -y [packages]
# [Continue with all setup commands]
```
### SSL Certificate
```bash
sudo certbot --nginx -d example.com
```
### Firewall Rules
```bash
sudo ufw allow [port]
sudo ufw allow from [IP] to any port [port]
```
---
## 8. Implementation Checklist
### Phase 0: Infrastructure Setup
- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]
### Phase 1: Core Foundation
- [ ] [Task 4]
- [ ] [Task 5]
- [ ] [Task 6]
### Phase 2: Features
- [ ] [Task 7]
- [ ] [Task 8]
### Phase 3: Testing & Launch
- [ ] [Task 9]
- [ ] [Task 10]
---
## 9. Migration/Integration
### Existing Systems Affected
| System | Impact | Migration Steps |
|--------|--------|-----------------|
| [System 1] | [Impact] | [Steps] |
### Data Migration
1. [Step 1]
2. [Step 2]
### Rollback Procedure
1. [Step 1]
2. [Step 2]
---
## 10. Emergency Contacts
If the primary implementer is unavailable:
1. **[Backup 1]** — [Why they can help, how to contact]
2. **[Backup 2]** — [Why they can help, how to contact]
3. **New AI session** — Start fresh with this document
---
## 11. Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | YYYY-MM-DD | [Name] | Initial creation |
---
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️