diff --git a/docs/standards/FFG-STD-005-implementation-guide-standard.md b/docs/standards/FFG-STD-005-implementation-guide-standard.md new file mode 100644 index 0000000..c692b8e --- /dev/null +++ b/docs/standards/FFG-STD-005-implementation-guide-standard.md @@ -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** 💙🔥❄️ diff --git a/docs/templates/implementation-guide-template.md b/docs/templates/implementation-guide-template.md new file mode 100644 index 0000000..2a95b19 --- /dev/null +++ b/docs/templates/implementation-guide-template.md @@ -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 + +``` + +[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** 💙🔥❄️