How to Use This TOC

This document provides two complementary views of the repository:

• From Top to Bottom: Complete inventory organized by capability and document type — for when you know which capability you need.
• Cross-Cutting Topics: Topic-based indexes that gather documents across capabilities — for when you know what you need but not where it lives.

Directory Indexes

Index documents for capability directories (references overviews of each directory's contents).

Document	Description
Checklists Index	Overview of checklist directories.
Accessibility Checklists Index	Overview of accessibility checklists.
Quality Checklists Index	Overview of quality checklists.
Rails Checklists Index	Overview of Rails checklists.
Glossary Index	Glossary organization and writing guidelines.
Accessibility Guides Index	Overview of accessibility guides.
Architecture Guides Index	Overview of architecture guides.
Engineering Guides Index	Overview of engineering guides.
Rails Guides Index	Overview of Rails guides.
Security Guides Index	Overview of security guides.
AI Playbooks Index	Overview of AI playbooks.
Code Review Playbook	Code review workflow.
Quality Playbooks Index	Overview of quality playbooks.
Rails Playbooks Index	Overview of Rails playbooks.
AI Workflows Index	Index of all AI workflow documents.
Accessibility Templates Index	Overview of accessibility templates.
AI Templates Index	Overview of AI templates.
Quality Templates Index	Overview of quality templates.
Rails Templates Index	Overview of Rails templates.
Security Templates Index	Overview of security templates.

From Top to Bottom

Governance

The foundational documents that define the framework itself.

Document	Description
CLAUDE.md	AI-specific project instructions for coding agents.
README.md	Repository overview, mission, vision and philosophy.
Strategy	Long-term vision and guiding strategy.
Roadmap	Strategic roadmap and phase progression.
Architecture	Repository architecture and knowledge organization.
Document Types	Canonical document taxonomy.
Style Guide	Writing, formatting and documentation standards.
Writing Principles	Philosophy behind effective engineering documentation.
Contributing	Contribution guidelines and workflows.
Changelog	Version history of the framework.
toc.md	This document — table of contents and indexes.

Engineering Fundamentals

Handbooks

Document	Description
Engineering Fundamentals Handbook	Core principles, quality philosophy, decision frameworks.

Glossaries

Document	Description
Engineering Glossary	Foundational terminology (abstraction, coupling, cohesion, etc.).

Guides

Document	Description
Code Organization	Feature-based packaging, module boundaries, anti-patterns.
Error Handling	Recoverable vs unrecoverable errors, patterns, logging.
Testing Strategies	Test pyramid, what to test, test doubles, anti-patterns.
Logging	Structured logging, log levels, context fields, anti-patterns.

Learning Paths

Document	Description
Engineering Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Engineering References	Quick lookup: principles, patterns, testing, logging.

AI Workflows

Document	Description
AI Workflows for Engineering	Prompt patterns for code review, refactoring, diagnosis.

Software Architecture

Handbooks

Document	Description
Software Architecture Handbook	Principles, patterns, decision frameworks, ADRs.

Glossaries

Document	Description
Architecture Glossary	Terminology (ADR, C4, DDD, hexagonal, trade-offs).

Guides

Document	Description
ADR Writing Guide	When and how to write Architecture Decision Records.
Architectural Patterns	Pattern catalogue with trade-offs and selection guidance.
API Design	RESTful conventions, versioning, error formats.
System Modeling	C4 model levels, event modeling techniques.

Playbooks

Document	Description
Architecture Review Playbook	Review workflow, team assembly, evaluation criteria.

Checklists

Document	Description
Architecture Review Checklist	Pre, during and post-review verification.
Design Decision Checklist	Before, during and after design decision verification.

Templates

Document	Description
ADR Template	Standard format for Architecture Decision Records.
RFC Template	Format for major architectural proposals.

Learning Paths

Document	Description
Architecture Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Architecture References	Quick lookup: C4, pattern comparison, HTTP codes.

AI Workflows

Document	Description
AI Workflows for Architecture	Prompt patterns for trade-off analysis, ADR drafting.

Rails Engineering

Handbooks

Document	Description
Rails Engineering Handbook	Principles, standards, patterns, decision frameworks.

Glossaries

Document	Description
Rails Glossary	Terminology (ActiveRecord, controller, service object, etc.).

Guides

Document	Description
Service Objects	When and how to use service objects, patterns, testing.
Testing Rails Applications	Test distribution, modelrequestsystem specs.
Rails Audit Guide	Systematic code quality, performance and security auditing.
Rails Project Standards	Mandatory tooling and CI*CD baseline for every project.
ActiveRecord Patterns	Scopes, query optimization, N+1 prevention, indexing.
API Development with Rails	API-only setup, serialization, versioning, auth.
Background Jobs	Framework selection, job design, error handling, monitoring.
Authentication and Authorization	Devise, Pundit, roles, anti-patterns.

Playbooks

Document	Description
Rails Upgrade Playbook	Step-by-step version upgrade with rollback plan.
Rails Deployment Playbook	Safe deployment with migration safety, zero-downtime.

Checklists

Document	Description
Rails Pull Request Checklist	Code quality, testing, security, migration safety.
Rails Security Review Checklist	Auth, data protection, dependency, infrastructure.
Rails Deployment Checklist	Pre-deploy, migration safety, post-deploy verification.

Templates

Document	Description
Service Object Template	Reusable pattern with result object.
Form Object Template	ActiveModel integration for complex forms.
Query Object Template	Composable scope chaining.
Policy Object Template	Authorization with Pundit conventions.

Learning Paths

Document	Description
Rails Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Rails References	Quick lookup: conventions, generators, gems, HTTP codes.

AI Workflows

Document	Description
AI Workflows for Rails	Prompt patterns for model gen, API dev, testing.

Security Engineering

Handbooks

Document	Description
Security Engineering Handbook	Principles, threat modeling, SDLC, standards.

Glossaries

Document	Description
Security Glossary	Terminology (CSRF, defense in depth, SAST, XSS, etc.).

Guides

Document	Description
Secure Coding Practices	Input validation, auth, output encoding, crypto.
Web Application Vulnerabilities	OWASP Top 10 with explanations and mitigations.
Dependency Security	Vulnerability scanning, selection, response, licensing.

Playbooks

Document	Description
Security Review Playbook	Review workflow, STRIDE threat modeling, remediation.

Checklists

Document	Description
Security Review Checklist	General security verification for any project.
Rails Security Review Checklist	Rails-specific security verification.

Learning Paths

Document	Description
Security Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Security References	Quick lookup: OWASP Top 10, STRIDE, tools, headers.

Templates

Document	Description
Threat Model Template	Structured threat model document using STRIDE.
Security Review Report	Findings report for security review outcomes.

AI Workflows

Document	Description
AI Workflows for Security	Prompt patterns for vulnerability ID, threat modeling.

Engineering Quality

Handbooks

Document	Description
Engineering Quality Handbook	Principles, quality gates, metrics, code review standards.

Glossaries

Document	Description
Engineering Quality Glossary	Terminology (change failure rate, MTTR, technical debt, etc.).

Guides

Document	Description
Code Review Standards	Standards for review velocity, what to review, severity labels.
Quality Metrics	Code quality and process metrics, implementation, pitfalls.
Technical Debt Management	Classification, assessment, management process.

Playbooks

Document	Description
Quality Review Playbook	Systematic quality assessment and reporting.
Technical Debt Remediation	Workflow for managing and reducing technical debt.
Release Quality Gate	Quality verification before production release.

Checklists

Document	Description
Quality Gate Checklist	Verification before accepting changes.
Release Readiness Checklist	Verification before production release.
Technical Debt Triage	Classification and prioritisation of technical debt.

Templates

Document	Description
Quality Report Template	Standard format for quality review reports.
Technical Debt Register	Track and monitor technical debt items.
Quality Dashboard Template	Template for tracking quality metrics.

Learning Paths

Document	Description
Engineering Quality Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Engineering Quality References	Quick lookup: gates, metrics targets, severity labels.

AI Workflows

Document	Description
AI Workflows for Quality	Prompt patterns for quality review, debt analysis, testing.

AI Engineering

Handbooks

Document	Description
AI Engineering Handbook	Principles, context engineering, AI workflow patterns, verification.

Glossaries

Document	Description
AI Engineering Glossary	Terminology (context engineering, hallucination, prompt engineering, verification).

Guides

Document	Description
Prompt Engineering	Principles, patterns (persona, format, constraint, verification) and anti-patterns.
Context Engineering	Context categories, templates for code, review and design.
AI Safety and Verification	Human oversight, high-risk use cases, prohibited uses, verification practices.
Agentic Workflows	Multi-step AI-assisted engineering workflow patterns.
AI Collaboration Patterns	How engineers and AI should interact in different contexts.
Human Review Strategies	When and how to review AI output effectively.
AI Evaluation Frameworks	Frameworks for measuring AI output quality and reliability.
Knowledge Extraction	Using AI to extract and structure engineering knowledge.

Playbooks

Document	Description
AI-Assisted Code Review	Workflow for reviewing code with AI assistance.
AI-Assisted Architecture Review	Workflow for architecture review with AI assistance.
AI Pair Programming	Workflow for collaborative coding with AI.
Verification Workflows	Systematic verification of AI-generated output.

Checklists

Document	Description
AI Usage Checklist	Verification checklist for AI-generated code, docs and architecture.

Templates

Document	Description
Context Pack Template	Structure for assembling AI context packs.
Prompt Template	Standard prompt structure for engineering AI.
AI Review Response Template	Format for documenting AI review findings.

Learning Paths

Document	Description
AI Engineering Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
AI Engineering References	Quick lookup: workflow patterns, context categories, failure modes.

AI Workflows

Document	Description
AI Workflows for AI Engineering	Prompt patterns for AI-assisted AI engineering tasks.

Accessibility Engineering

Handbooks

Document	Description
Accessibility Engineering Handbook	Principles, WCAG standards, testing, AI integration.

Glossaries

Document	Description
Accessibility Glossary	Terminology (WCAG, ARIA, screen reader, colour contrast).

Guides

Document	Description
Semantic HTML	Using HTML elements for their intended purpose.
Keyboard Accessibility	Ensuring full keyboard operability.
Accessible Forms	Building forms that work for everyone.
ARIA Patterns	Using ARIA correctly for custom widgets.
Colour and Contrast	Meeting colour contrast requirements.
Screen Reader Testing	Testing with assistive technologies.

Playbooks

Document	Description
Accessibility Review Playbook	Workflow for reviewing digital accessibility.

Checklists

Document	Description
WCAG Audit Checklist	Comprehensive WCAG compliance audit.
PR Accessibility Checklist	Quick accessibility checks for every pull request.
Design Review Checklist	Accessibility checks during the design phase.

Templates

Document	Description
Accessibility Report	Standard format for accessibility audit findings.
Accessibility Statement	Public-facing accessibility statement.

Learning Paths

Document	Description
Accessibility Learning Paths	Beginnerintermediateadvanced tracks.

References

Document	Description
Accessibility References	Quick lookup: WCAG levels, contrast ratios, ARIA landmarks.

AI Workflows

Document	Description
AI Workflows for Accessibility	Prompt patterns for auditing, remediation and testing.

Cross-Cutting Topics

The following indexes gather documents across capabilities by topic.

Testing

Capability	Document	Type	Description
Engineering	Testing Strategies	Guide	Test pyramid, what to test, test doubles.
Rails	Testing Rails Applications	Guide	Modelrequestsystem specs, factory patterns.
Rails	Rails Pull Request Checklist	Checklist	Testing verification for every PR.
Architecture	Architecture Review Playbook	Playbook	Review criteria includes testability.

API Design and Development

Capability	Document	Type	Description
Architecture	API Design	Guide	RESTful conventions, versioning, status codes.
Rails	API Development with Rails	Guide	Rails-specific API setup, serialization, auth.
Rails	Rails Engineering Handbook	Handbook	API standards and conventions section.

Error Handling

Capability	Document	Type	Description
Engineering	Error Handling	Guide	Principles, patterns, logging, anti-patterns.
Engineering	Logging	Guide	Structured logging, log levels, context.
Rails	Service Objects	Guide	Error handling in service objects.
Rails	Rails Engineering Handbook	Handbook	Error handling standards.

Performance

Capability	Document	Type	Description
Rails	Rails Audit Guide	Guide	Performance profiling, N+1 detection, APM.
Rails	ActiveRecord Patterns	Guide	Query optimization, N+1 prevention, indexing.
Rails	Background Jobs	Guide	Job performance, queue monitoring.

Security

Capability	Document	Type	Description
Security	Security Engineering Handbook	Handbook	Principles, threat modeling, SDLC.
Security	Secure Coding Practices	Guide	Input validation, auth, crypto.
Security	Web Vulnerabilities	Guide	OWASP Top 10 with mitigations.
Security	Dependency Security	Guide	Vulnerability scanning, response.
Security	Security Review Playbook	Playbook	Threat modeling, review workflow.
Security	Security Review Checklist	Checklist	General security verification.
Rails	Rails Security Review Checklist	Checklist	Rails-specific security checks.
Rails	Rails Audit Guide	Guide	Security auditing section.

Architecture Decisions

Capability	Document	Type	Description
Architecture	Architecture Handbook	Handbook	Decision frameworks, ADR standards.
Architecture	ADR Writing Guide	Guide	When and how to write ADRs.
Architecture	ADR Template	Template	Standard ADR format.
Architecture	RFC Template	Template	Major proposal format.
Architecture	Design Decision Checklist	Checklist	Beforeduringafter decision verification.

Architecture Decision Records

Document	Description
ADR 0001: Capability Model	Knowledge organization around capabilities.
ADR 0002: Org-Mode Format	Org-mode as primary document format.
ADR 0003: Document Taxonomy	Nine document types with single responsibility.
ADR 0004: AI-Native Knowledge Design	AI as first-class knowledge consumer.
ADR 0005: Foundation Capabilities First	Build fundamentals before technology capabilities.
ADR 0006: Per-Capability Glossaries	Glossaries organized by capability.

Project Setup and Standards

Capability	Document	Type	Description
Rails	Rails Project Standards	Guide	Mandatory tooling, CI*CD baseline.
Rails	Rails Deployment Playbook	Playbook	Safe deployment with migrations.
Rails	Rails Deployment Checklist	Checklist	Pre/post-deploy verification.
Engineering	Tech Debt Assessment	Checklist	Debt identification and tracking.

Quality

Capability	Document	Type	Description
Quality	Engineering Quality Handbook	Handbook	Quality principles, gates, metrics.
Quality	Code Review Standards	Guide	Review velocity, what to review.
Quality	Quality Metrics	Guide	Code quality and process metrics.
Quality	Technical Debt Management	Guide	Debt classification and management.
Quality	Quality Review Playbook	Playbook	Systematic quality assessment.
Quality	Technical Debt Remediation	Playbook	Managing and reducing technical debt.
Quality	Release Quality Gate	Playbook	Quality verification before release.
Quality	Quality Gate Checklist	Checklist	Verification before accepting changes.
Quality	Release Readiness Checklist	Checklist	Verification before production release.
Quality	Technical Debt Triage	Checklist	Classification and prioritisation.
Quality	Quality Report Template	Template	Standard quality review report format.
Quality	Technical Debt Register	Template	Track and monitor technical debt.
Quality	Quality Dashboard Template	Template	Track quality metrics over time.
Quality	AI Workflows for Quality	AI Work	Prompt patterns for quality review.

AI and Engineering

Capability	Document	Type	Description
AI Engineering	AI Engineering Handbook	Handbook	AI principles, context engineering,
			workflow patterns.
	Prompt Engineering	Guide	Patterns and anti-patterns for prompt
			design.
	Context Engineering	Guide	Providing effective context to AI.
	AI Safety and Verification	Guide	Safe and responsible AI use practices.
	Agentic Workflows	Guide	Multi-step AI-assisted workflows.
	AI Collaboration Patterns	Guide	Engineer-AI interaction models.
	Human Review Strategies	Guide	Reviewing AI output effectively.
	AI Evaluation Frameworks	Guide	Measuring AI output quality.
	Knowledge Extraction	Guide	Extracting knowledge with AI.
	AI-Assisted Code Review	Playbook	AI-assisted code review workflow.
	AI-Assisted Architecture Review	Playbook	AI-assisted architecture review.
	AI Pair Programming	Playbook	Collaborative coding with AI.
	Verification Workflows	Playbook	Systematic AI output verification.
	AI Usage Checklist	Checklist	Verification for AI-generated output.
	Context Pack Template	Template	Structure for AI context packs.
	Prompt Template	Template	Standard prompt structure.
	AI Engineering References	Reference	Workflow patterns, failure modes.
Engineering	AI Workflows for Engineering	AI Work	Prompt patterns for code review, design
			exploration, refactoring.
Architecture	AI Workflows for Architecture	AI Work	Prompt patterns for trade-off analysis,
			ADR drafting, pattern selection.
Rails	AI Workflows for Rails	AI Work	Prompt patterns for model gen, API dev,
			testing.
Security	AI Workflows for Security	AI Work	Prompt patterns for vulnerability ID,
			threat modeling.
Quality	AI Workflows for Quality	AI Work	Prompt patterns for quality review.
Accessibility	AI Workflows for Accessibility	AI Work	Prompt patterns for accessibility.
AI Engineering	AI Workflows for AI Engineering	AI Work	Prompt patterns for AI engineering.

Related Documents

• Repository Overview
• Roadmap
• Style Guide