Ref-006: Documentation System Structure & AI Workflow Integration

Type

Reference Documentation

Purpose

Defines the documentation hub structure, AI-enhanced development workflows, and template-driven documentation generation approach for the SEA-Forge™ platform powered by VibesPro™.

System Origin

Generated by VibesPro™’s HexDDD + VibePDK merger, ensuring production-ready, spec-driven guidance from project inception.

Documentation Architecture

Core Files

File	Purpose
`README.md`	Orientation and navigation guide
`spec_index.md`	Snapshot of product requirements and design references
`dev_spec_index.md`	Developer-focused specification overview for tooling and DX
`traceability_matrix.md`	Living record connecting specs to implemented artifacts
`commit_message_guidelines.md`	Traceable, spec-aware commit expectations (see REF-002)

Directory Structure

Directory	Content
`how-to/`	Procedure-driven guides for onboarding, AI workflows, validation
`docs/architecture/`	Architectural decisions and domain documentation
`templates/sea/docs/`	Template sources for documentation generation

Generator-First Philosophy

Principle: Update the template if a guide needs to change, so future projects inherit improvements automatically.

Template Sources

Located in templates/sea/docs/ (generator repository)
Regenerates dependent projects for ecosystem consistency
Maintains traceability across teams

AI-Enhanced Development Workflows

Core Capabilities

1. Temporal Learning

Captures architectural decisions and feeds future recommendations, forming a persistent knowledge base for AI agents.

2. Context-Aware Prompts

Ensures GitHub Copilot and MCP tools respect domain boundaries and architectural constraints.

3. Spec Enforcement

Maintains synchronization of ADR/PRD/SDS/TS references through automation.

Onboarding

See how-to/ai-onboarding.md for step-by-step walkthrough of:

Enabling augmented workflows in fresh repositories
Linking to traceability matrix
Integrating commit message guidelines

Maintainer Workflows

Essential Tasks

Install Dependencies & Generate Reports

pnpm install
pnpm spec:matrix  # Regenerate traceability reports

Verify Prompt Governance

pnpm prompt:lint  # Validate before shipping updates

Capture Architectural Decisions
- Document in docs/architecture/
- Use temporal DB helpers for persistence
Maintain AI Onboarding
- Keep AI onboarding guide aligned with secrets management process
- Update for team-specific tooling

Template Extension Process

When New Patterns Emerge

Update Template Sources
- Modify templates/sea/docs/ in generator repository
- Follow template-first philosophy
Regenerate Dependent Projects
- Apply changes across ecosystem
- Maintain consistency and traceability
Validate Changes
- Run pnpm prompt:lint
- Verify traceability matrix updates

Integration Points

Referenced Standards

Commit messages: REF-002 (Commit Message Standards)
ADR structure: REF-001 (ADR Template Structure)
PRD structure: REF-005 (PRD Template Structure)
Markdown quality: REF-003 (Markdown Linting Standards)
Scaffolding: REF-004 (Nx Generator Standards)

NPM Scripts

pnpm spec:matrix: Traceability report generation
pnpm prompt:lint: Prompt governance validation

External Tools

GitHub Copilot: Context-aware code generation
MCP (Model Context Protocol): Domain-aware tooling
Temporal DB: Architectural decision persistence

Key Principles

Template-Driven: All documentation generated from Copier templates
Spec-Driven: Requirements and designs drive implementation
AI-Augmented: Copilot and MCP integration by default
Traceable: Living connections between specs and code
Consistent: Ecosystem-wide patterns enforced via templates

VibesPro™ Platform Components

HexDDD

Hexagonal Domain-Driven Design framework providing structural patterns.

VibePDK

Platform Development Kit for AI-enhanced workflows and tooling.

Temporal Learning

Persistent knowledge capture and recommendation engine for architectural decisions.