FP&A Platform Artifact Naming Convention Standard

Document ID: STD-NCS-001
Version: 3.0
Effective Date: 2026-02-03
Owner: CODITECT Platform Engineering
TRACK Task Type: STANDARD

---

1. Purpose & Scope

This standard establishes the authoritative naming convention for all artifacts in the AI-First Open-Source FP&A Platform project. Adherence is mandatory for all team members, automated systems, and TRACK task assignments.

Benefits

Benefit	Impact
Discoverability	Find any artifact in <10 seconds
Automation	TRACK task assignment by prefix
Audit Trail	Clear ownership and version history
Scalability	Supports 1000+ artifacts without confusion
CI/CD Integration	Automated validation enforcement

---

2. Master Naming Pattern

2.1 Standard Format

[PREFIX]-[CATEGORY]-[SEQUENCE]-[descriptor].[extension]

2.2 Component Specification

Component	Format	Constraint	Example
PREFIX	2-4 uppercase letters	Required, from approved list	SPEC, ADR, MOD
CATEGORY	2-4 uppercase letters	Required, from approved list	FPA, SEC, GL
SEQUENCE	3-digit zero-padded	Required, unique per PREFIX-CATEGORY	001, 042, 000
descriptor	kebab-case lowercase	Required, 2-50 chars, alphanumeric + hyphens	product-requirements
extension	lowercase	Required, standard extension	.md, .xlsx, .yaml

2.3 Regex Validation Pattern

^[A-Z]{2,4}-[A-Z]{2,4}-[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*\.(md|xlsx|yaml|json|sql|py|pptx|pdf|docx|html|mermaid)$

2.4 Examples

✅ SPEC-FPA-001-product-requirements.md
✅ ADR-SEC-001-openfga-authorization.md
✅ FIN-ROI-001-customer-calculator.xlsx
✅ SQL-DB-001-complete-schema.sql
✅ CFG-INT-001-airbyte-connectors.yaml

❌ FPA-PRD.md                    # Missing PREFIX-CATEGORY-SEQ pattern
❌ 01-ROI-Calculator.xlsx        # Invalid prefix format
❌ SPEC_FPA_001_product.md       # Uses underscores instead of hyphens
❌ spec-fpa-001-product.md       # Lowercase prefix

---

3. Document Type Prefixes (Complete Reference)

3.1 Specifications & Architecture

Prefix	Name	Description	Extension	TRACK Type
SPEC	Specification	PRD, SDD, TDD, Test Strategy	.md	SPECIFICATION
ADR	Architecture Decision Record	Technology decisions with rationale	.md	ARCHITECTURE
REQ	Requirements	Functional/non-functional requirements	.md	SPECIFICATION
ARC	Architecture	Architecture overview documentation	.md	ARCHITECTURE
C4	C4 Diagram	Context, Container, Component, Code	.md	ARCHITECTURE
EVT	Event Catalog	Domain events, schemas, flows	.md	ARCHITECTURE
SEQ	Sequence Diagram	Process flows, API interactions	.md	ARCHITECTURE
ERD	Entity Relationship	Database diagrams, data models	.md	DATABASE

3.2 Research & Analysis

Prefix	Name	Description	Extension	TRACK Type
ANL	Analysis	Strategic analysis, assessments, gap analysis	.md	ANALYSIS
RES	Research	Deep research outputs, market research	.md	RESEARCH
PRM	Prompt	Research prompts for AI execution	.md	RESEARCH
MOD	Module	Module-level research and design prompts	.md	RESEARCH
MKT	Market	Market analysis, competitive intelligence	.md	ANALYSIS

3.3 Technical Artifacts

Prefix	Name	Description	Extension	TRACK Type
SQL	SQL Schema	Database schemas, migrations	.sql	DATABASE
CFG	Configuration	Infrastructure, pipeline, service configs	.yaml, .json	INFRASTRUCTURE
WFL	Workflow	LangGraph, Dagster, Airflow definitions	.yaml, .py	DEVELOPMENT
API	API Specification	OpenAPI, GraphQL schemas	.yaml, .json	DEVELOPMENT
SCR	Script	Utility scripts, automation	.py, .sh, .ts	DEVELOPMENT

3.4 Compliance & Governance

Prefix	Name	Description	Extension	TRACK Type
CMP	Compliance	Regulatory compliance requirements	.md	COMPLIANCE
RGU	Regulatory Update	Regulatory change documentation	.md	COMPLIANCE
GOV	Governance	Policies, standards, procedures	.md	COMPLIANCE
AUD	Audit	Audit evidence, reports, findings	.md, .xlsx	COMPLIANCE
CTL	Control	Control matrices, testing evidence	.xlsx	COMPLIANCE

3.5 Security & Operations

Prefix	Name	Description	Extension	TRACK Type
SEC	Security	Security specifications, assessments	.md	SECURITY
THR	Threat	Threat models, risk assessments	.md	SECURITY
DRP	Disaster Recovery	DR plans, runbooks	.md	OPERATIONS
MON	Monitoring	Monitoring specs, alerting	.md	OPERATIONS
OPS	Operations	Operational procedures	.md	OPERATIONS

3.6 Business & Financial

Prefix	Name	Description	Extension	TRACK Type
FIN	Financial Model	Excel financial models, calculators	.xlsx	FINANCIAL
BUS	Business Case	ROI analysis, TCO comparison	.xlsx, .md	FINANCIAL
PRC	Pricing	Pricing models, rate cards	.xlsx	FINANCIAL

3.7 Documentation

Prefix	Name	Description	Extension	TRACK Type
DOC	Documentation	General documentation	.md	DOCUMENTATION
GDE	Guide	User guides, admin guides	.md	DOCUMENTATION
REF	Reference	API reference, technical reference	.md	DOCUMENTATION
PLB	Playbook	Operational playbooks, runbooks	.md	DOCUMENTATION

3.8 Templates & Training

Prefix	Name	Description	Extension	TRACK Type
TPL	Template	Reusable templates, forms	.xlsx, .md	TEMPLATE
TRN	Training	Training materials	.pptx, .md	TRAINING

3.9 Project Management

Prefix	Name	Description	Extension	TRACK Type
PRJ	Project	Project plans, status reports	.md	PROJECT
INV	Inventory	Artifact inventories, registries	.md	PROJECT
MST	Master	Master prompts, orchestration	.md	PROJECT
STD	Standard	Standards, conventions	.md	STANDARD
TRK	Track	TRACK assignments, sprints	.yaml	PROJECT
RPT	Report	Validation reports, status reports	.json, .yaml	PROJECT

---

4. Category Codes

4.1 Domain Categories

Code	Domain	Example
FPA	FP&A Platform (general)	SPEC-FPA-001
GL	General Ledger	MOD-GL-001
COA	Chart of Accounts	MOD-COA-001
JRN	Journal Entry	MOD-JRN-001
TRB	Trial Balance	MOD-TRB-001
FNS	Financial Statements	MOD-FNS-001
BUD	Budget	MOD-BUD-001
FCT	Forecast	MOD-FCT-001
VAR	Variance Analysis	MOD-VAR-001
REC	Reconciliation	MOD-REC-001
CON	Consolidation	MOD-CON-001
KPI	KPI Dashboard	MOD-KPI-001
AGT	AI Agent	MOD-AGT-001
NLG	Natural Language	MOD-NLG-001

4.2 Technical Categories

Code	Domain	Example
DB	Database	SQL-DB-001
INT	Integration	CFG-INT-001
INF	Infrastructure	CFG-INF-001
SEC	Security	CFG-SEC-001
AI	AI/ML	WFL-AI-001
ARC	Architecture	ADR-ARC-001
SYS	System	SEC-SYS-001
OBS	Observability	MON-OBS-001

4.3 Compliance & Geographic Categories

Code	Domain	Example
US	United States	CMP-US-001
BR	Brazil	CMP-BR-001
SOX	SOX Compliance	TPL-SOX-001
LGP	LGPD	CMP-LGP-001
HIP	HIPAA	CMP-HIP-001
FDA	FDA 21 CFR 11	CMP-FDA-001
BCN	BACEN	CMP-BCN-001

4.4 Project Categories

Code	Domain	Example
PRJ	Project Management	INV-PRJ-000
NCS	Naming Convention Standard	STD-NCS-001
VAL	Validation	RPT-VAL-001

---

5. Sequence Number Ranges

Range	Purpose	Example
000	Index/Master documents	INV-PRJ-000, PRM-MOD-000
001-099	Core/Foundation	SPEC-FPA-001, ADR-SEC-001
100-199	Primary Features	MOD-GL-100
200-299	Secondary Features	MOD-FCT-200
300-399	Advanced Features	MOD-AGT-300
400-499	Compliance	CMP-US-401
500-599	Integration	INT-ERP-501
600-699	Reporting/Analytics	REP-KPI-601
700-799	Documentation	DOC-USR-701
800-899	Templates	TPL-SOX-801
900-999	Project Management	TRK-PRJ-901

---

6. Directory Structure

fpa-platform/
├── 00-project/          # Project management, inventory, standards
├── 01-specs/            # Specifications (PRD, SDD, TDD)
├── 02-architecture/     # Architecture (ADRs, C4, events)
│   ├── adrs/
│   ├── c4/
│   ├── events/
│   └── data/
├── 03-modules/          # Module research prompts
│   ├── core/
│   ├── planning/
│   ├── operations/
│   ├── reporting/
│   └── ai/
├── 04-compliance/       # Compliance documentation
│   ├── us/
│   └── br/
├── 05-integration/      # Integration prompts
│   ├── erp/
│   ├── banking/
│   └── platform/
├── 06-technical/        # Technical artifacts
│   ├── sql/
│   ├── config/
│   ├── workflows/
│   └── scripts/
├── 07-financial/        # Financial models
├── 08-security/         # Security artifacts
├── 09-operations/       # Operations artifacts
├── 10-documentation/    # Documentation
├── 11-templates/        # Templates
└── 12-training/         # Training materials

---

7. Migration Mapping (Legacy → STD-NCS-001)

7.1 Analysis Outputs

Legacy Name	Standard Name
01-EXECUTIVE-ANALYSIS.md	ANL-PRJ-001-executive-analysis.md
02-CODITECT-IMPACT-ANALYSIS.md	ANL-PRJ-002-coditect-impact.md
03-RESEARCH-PROMPTS-TIER1.md	PRM-PRJ-003-research-tier1.md
04-RESEARCH-PROMPTS-TIER2.md	PRM-PRJ-004-research-tier2.md
05-CODITECT-PRODUCT-IDEAS.md	ANL-PRJ-005-product-ideas.md
06-STRATEGIC-RECOMMENDATION.md	ANL-PRJ-006-strategic-recommendation.md

7.2 Specifications

Legacy Name	Standard Name
FPA-PRD.md	SPEC-FPA-001-product-requirements.md
FPA-SDD.md	SPEC-FPA-002-software-design.md
FPA-TDD.md	SPEC-FPA-003-technical-design.md
FPA-TEST-STRATEGY.md	SPEC-FPA-004-test-strategy.md

7.3 Architecture

Legacy Name	Standard Name
ARCHITECTURE-DECISIONS.md	ADR-ARC-000-decisions-index.md
C4-ARCHITECTURE-DIAGRAMS.md	C4-ARC-001-architecture-diagrams.md
EVENT-CATALOG.md	EVT-ARC-001-event-catalog.md

7.4 Research Prompts

Legacy Name	Standard Name
MODULE-RESEARCH-PROMPTS.md	PRM-MOD-000-module-prompts-index.md
US-COMPLIANCE-PROMPTS.md	PRM-CMP-001-us-compliance.md
BR-COMPLIANCE-PROMPTS.md	PRM-CMP-002-br-compliance.md
INTEGRATION-RESEARCH-PROMPTS.md	PRM-INT-000-integration-prompts-index.md
MISSING-ARTIFACT-PROMPTS.md	PRM-PRJ-001-missing-artifacts.md

7.5 Compliance

Legacy Name	Standard Name
BR-REGULATORY-UPDATES-2025-2026.md	RGU-BR-001-regulatory-updates-2026.md

7.6 Technical

Legacy Name	Standard Name
FPA-COMPLETE-SCHEMA.sql	SQL-DB-001-complete-schema.sql
airbyte-connectors.yaml	CFG-INT-001-airbyte-connectors.yaml
dagster-pipelines.yaml	CFG-INT-002-dagster-pipelines.yaml
openfga-authorization.yaml	CFG-SEC-001-openfga-authorization.yaml
langgraph-workflows.yaml	WFL-AI-001-langgraph-workflows.yaml
terraform-infrastructure.yaml	CFG-INF-001-terraform-infrastructure.yaml

7.7 Financial Models

Legacy Name	Standard Name
01-ROI-Calculator.xlsx	FIN-ROI-001-customer-calculator.xlsx
02-Month-End-Close-Savings.xlsx	FIN-OPS-001-close-savings.xlsx
03-13-Week-Cash-Flow.xlsx	FIN-FCT-001-cash-flow-13week.xlsx
04-Budget-vs-Actual.xlsx	FIN-VAR-001-budget-vs-actual.xlsx
05-Platform-Pricing.xlsx	FIN-PRC-001-platform-pricing.xlsx
06-Implementation-Cost-Model.xlsx	FIN-PRJ-001-implementation-cost.xlsx

7.8 Security & Operations

Legacy Name	Standard Name
SECURITY-SPECIFICATION.md	SEC-SYS-001-security-specification.md
DATA-CLASSIFICATION-MATRIX.md	GOV-SEC-001-data-classification.md
DISASTER-RECOVERY-PLAN.md	DRP-OPS-001-disaster-recovery.md
MONITORING-ALERTING-SPEC.md	MON-OBS-001-monitoring-alerting.md

7.9 Documentation

Legacy Name	Standard Name
DATA-DICTIONARY.md	DOC-DB-001-data-dictionary.md
AI-MODEL-CARDS.md	DOC-AI-001-model-cards.md
PROMPT-ENGINEERING-PLAYBOOK.md	PLB-AI-001-prompt-engineering.md

7.10 Inventory & Standards

Legacy Name	Standard Name
00-DOCUMENT-INVENTORY-v2.md	INV-PRJ-000-artifact-inventory.md
ARTIFACT-GAP-ANALYSIS-v2.md	ANL-PRJ-002-artifact-gap-analysis.md

---

8. TRACK Task Type Mapping

Each PREFIX maps to a TRACK Task Type for automated assignment:

track_task_mapping:
  # Specifications
  SPEC: SPECIFICATION
  ADR: ARCHITECTURE
  REQ: SPECIFICATION
  
  # Research
  ANL: ANALYSIS
  RES: RESEARCH
  PRM: RESEARCH
  MOD: RESEARCH
  MKT: ANALYSIS
  
  # Architecture
  ARC: ARCHITECTURE
  C4: ARCHITECTURE
  EVT: ARCHITECTURE
  SEQ: ARCHITECTURE
  ERD: DATABASE
  
  # Technical
  SQL: DATABASE
  CFG: INFRASTRUCTURE
  WFL: DEVELOPMENT
  API: DEVELOPMENT
  SCR: DEVELOPMENT
  
  # Compliance
  CMP: COMPLIANCE
  RGU: COMPLIANCE
  GOV: COMPLIANCE
  AUD: COMPLIANCE
  CTL: COMPLIANCE
  
  # Security & Operations
  SEC: SECURITY
  THR: SECURITY
  DRP: OPERATIONS
  MON: OPERATIONS
  OPS: OPERATIONS
  
  # Financial
  FIN: FINANCIAL
  BUS: FINANCIAL
  PRC: FINANCIAL
  
  # Documentation
  DOC: DOCUMENTATION
  GDE: DOCUMENTATION
  REF: DOCUMENTATION
  PLB: DOCUMENTATION
  
  # Templates & Training
  TPL: TEMPLATE
  TRN: TRAINING
  
  # Project
  PRJ: PROJECT
  INV: PROJECT
  MST: PROJECT
  STD: STANDARD
  TRK: PROJECT
  RPT: PROJECT

---

9. Validation Tools

9.1 Python Validation Script

#!/usr/bin/env python3
"""STD-NCS-001 Naming Convention Validator"""

import re
import sys
from pathlib import Path

NAMING_PATTERN = re.compile(
    r'^[A-Z]{2,4}-[A-Z]{2,4}-[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*\.'
    r'(md|xlsx|yaml|json|sql|py|pptx|pdf|docx|html|mermaid)$'
)

VALID_PREFIXES = {
    'SPEC', 'ADR', 'REQ', 'ARC', 'C4', 'EVT', 'SEQ', 'ERD',
    'ANL', 'RES', 'PRM', 'MOD', 'MKT',
    'SQL', 'CFG', 'WFL', 'API', 'SCR',
    'CMP', 'RGU', 'GOV', 'AUD', 'CTL',
    'SEC', 'THR', 'DRP', 'MON', 'OPS',
    'FIN', 'BUS', 'PRC',
    'DOC', 'GDE', 'REF', 'PLB',
    'TPL', 'TRN',
    'PRJ', 'INV', 'MST', 'STD', 'TRK', 'RPT'
}

def validate_file(filepath: Path) -> tuple[bool, str]:
    """Validate a single file against STD-NCS-001."""
    name = filepath.name
    
    # Skip hidden files
    if name.startswith('.'):
        return True, "Skipped (hidden)"
    
    # Check pattern match
    if not NAMING_PATTERN.match(name):
        return False, "Pattern mismatch"
    
    # Extract and validate prefix
    prefix = name.split('-')[0]
    if prefix not in VALID_PREFIXES:
        return False, f"Invalid prefix: {prefix}"
    
    return True, "Valid"

def validate_directory(directory: Path, recursive: bool = True) -> dict:
    """Validate all files in a directory."""
    results = {
        'valid': [],
        'invalid': [],
        'skipped': []
    }
    
    files = directory.rglob('*') if recursive else directory.glob('*')
    
    for f in files:
        if f.is_file():
            is_valid, reason = validate_file(f)
            if reason == "Skipped (hidden)":
                results['skipped'].append(str(f))
            elif is_valid:
                results['valid'].append(str(f))
            else:
                results['invalid'].append((str(f), reason))
    
    return results

if __name__ == '__main__':
    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path('.')
    results = validate_directory(target)
    
    print(f"✅ Valid: {len(results['valid'])}")
    print(f"❌ Invalid: {len(results['invalid'])}")
    print(f"⏭️ Skipped: {len(results['skipped'])}")
    
    if results['invalid']:
        print("\n❌ Invalid files:")
        for f, reason in results['invalid']:
            print(f"  - {f}: {reason}")
        sys.exit(1)

9.2 Bash Validation One-Liner

find . -type f -name '*.md' -o -name '*.xlsx' -o -name '*.yaml' | \
  xargs -I {} basename {} | \
  grep -vE '^[A-Z]{2,4}-[A-Z]{2,4}-[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*\.(md|xlsx|yaml)$'

---

10. Quick Reference Card

┌─────────────────────────────────────────────────────────────────────┐
│  STD-NCS-001 v3.0 — FP&A PLATFORM NAMING CONVENTION                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  PATTERN: [PREFIX]-[CATEGORY]-[SEQ]-[descriptor].[ext]             │
│  EXAMPLE: SPEC-FPA-001-product-requirements.md                      │
│                                                                     │
│  ─────────────────────────────────────────────────────────────────  │
│  TOP 20 PREFIXES                                                    │
│  ─────────────────────────────────────────────────────────────────  │
│  SPEC = Specification      ADR = Architecture Decision              │
│  MOD  = Module Prompt      PRM = Research Prompt                    │
│  CFG  = Configuration      SQL = Database Schema                    │
│  FIN  = Financial Model    CMP = Compliance                         │
│  DOC  = Documentation      TPL = Template                           │
│  TRN  = Training           MST = Master Prompt                      │
│  INV  = Inventory          TRK = TRACK Assignment                   │
│  STD  = Standard           RGU = Regulatory Update                  │
│  SEC  = Security           WFL = Workflow                           │
│  ANL  = Analysis           PLB = Playbook                           │
│                                                                     │
│  ─────────────────────────────────────────────────────────────────  │
│  TOP 15 CATEGORIES                                                  │
│  ─────────────────────────────────────────────────────────────────  │
│  FPA = Platform            PRJ = Project                            │
│  GL  = General Ledger      REC = Reconciliation                     │
│  FCT = Forecast            BUD = Budget                             │
│  INT = Integration         SEC = Security                           │
│  INF = Infrastructure      DB  = Database                           │
│  AI  = AI/ML               OBS = Observability                      │
│  US  = United States       BR  = Brazil                             │
│  ARC = Architecture                                                 │
│                                                                     │
│  ─────────────────────────────────────────────────────────────────  │
│  SEQUENCE RANGES                                                    │
│  ─────────────────────────────────────────────────────────────────  │
│  000       = Index/Master               500-599 = Integration       │
│  001-099   = Core/Foundation            700-799 = Documentation     │
│  100-199   = Primary Features           800-899 = Templates         │
│  200-299   = Secondary Features         900-999 = Project Mgmt      │
│  400-499   = Compliance                                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

11. Governance

11.1 Enforcement

Phase	Timeline	Requirement
Awareness	Week 1	All team members trained
Soft Enforcement	Weeks 2-4	Warnings for non-compliance
Hard Enforcement	Week 5+	CI/CD blocks non-compliant PRs
Legacy Migration	30 days	All existing artifacts migrated

11.2 Change Process

Submit changes via GitHub Issue with label naming-convention. Changes require:

• Technical Lead approval for prefix/category changes
• Platform Lead approval for pattern changes

11.3 Version History

Version	Date	Changes
3.0	2026-02-03	Standalone artifact, complete migration mapping, TRACK integration
2.0	2026-02-03	Complete rewrite with validation tools
1.0	2026-02-03	Initial release

---

STD-NCS-001 v3.0 — FP&A Platform Artifact Naming Convention Standard
CODITECT Platform Engineering
Effective: 2026-02-03