@akson/cortex-doc-standards

Documentation standards and tooling for Cortex repositories. Provides CLAUDE.md generation, documentation rules, and MCP server integration for Claude AI workflows.

Features

• 📝 CLAUDE.md Generation - Generate optimized CLAUDE.md files from rules
• 🔧 Rules Management - Initialize and manage documentation rules
• 🔌 MCP Server - Model Context Protocol server for Claude AI integration
• 🎯 Standards Enforcement - Documentation quality and naming conventions
• 🚀 CLI Tools - Simple command-line interface for common tasks

Installation

npm install @akson/cortex-doc-standards

Quick Start

# Initialize rules in your project
npx cortex-doc-standards rules init

# Generate CLAUDE.md from rules
npx cortex-doc-standards generate

# Start MCP server for Claude AI
npx cortex-doc-standards-mcp

📋 Configuration Examples

Ready-to-use configuration examples for different project types:

# Copy a project-specific example
cp node_modules/@akson/cortex-doc-standards/examples/nextjs-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/flutter-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/backend-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-monorepo-config.json ./doc-standards.config.json
cp node_modules/@akson/cortex-doc-standards/examples/makerkit-flutter-config.json ./doc-standards.config.json

# Or start with the comprehensive base example
cp node_modules/@akson/cortex-doc-standards/examples/base-config.json ./doc-standards.config.json

Available Examples:

• base-config.json - Comprehensive configuration with all rules
• nextjs-config.json - Next.js application with TypeScript & Prisma
• monorepo-config.json - Turbo monorepo with shared packages
• flutter-config.json - Cross-platform Flutter mobile app
• backend-config.json - Node.js API server with database
• makerkit-monorepo-config.json - MakerKit SaaS framework with Turborepo
• makerkit-flutter-config.json - MakerKit web + Flutter mobile cross-platform

See examples/README.md for detailed configuration guide.

CLI Commands

CLAUDE.md Generation (Recommended Workflow)

# 1. Initialize rules configuration (auto-detects project type)
npx cortex-doc-standards rules init

# 2. Edit .cortex-doc-standards/rules.json to customize your rules

# 3. Generate CLAUDE.md from your rules
npx cortex-doc-standards generate

Available Built-in Rules

The package includes 6 optimized built-in rules that cover all aspects of AI-assisted development:

| Rule ID | Purpose | Description | |---------|---------|-------------| | claude-essentials | Core AI Behavior | Consolidated Claude communication, tool usage, and workflow fundamentals | | code-standards | Quality & Naming | File naming conventions, quality gates, and version suffix prohibition | | security-standards | Security & Testing | Security practices, secrets management, and testing requirements | | testing-standards | Test Organization | Comprehensive testing standards and commands (merged with security) | | project-workflow | Project Integration | GitHub issue tracking and shared package management | | makerkit-complete | MakerKit Framework | Complete MakerKit development patterns and best practices |

Rule Configuration Variables

Each rule supports customization through variables. Here are the key variables for each rule:

claude-essentials

{
  "package.file": "package.json",           // Package config file
  "translation.function": "t",              // i18n function name
  "lint.command": "pnpm lint",             // Linting command
  "typecheck.command": "pnpm typecheck",   // Type checking command
  "test.command": "pnpm test"              // Test command
}

security-standards

{
  "secrets.manager": "1Password",          // Secrets management system
  "auth.method": "Supabase Auth",          // Authentication method
  "security.scanCommand": "pnpm audit"    // Security scan command
}

testing-standards

{
  "coverage.unit": "80",                   // Minimum unit test coverage
  "test.unit": "pnpm test",               // Unit test command
  "test.integration": "pnpm run test:integration",
  "test.e2e": "pnpm run test:e2e",
  "test.watch": "pnpm run test:watch",
  "test.coverage": "pnpm run test:coverage",
  "test.directory": "__tests__",          // Test directory
  "test.extension": "ts"                  // Test file extension
}

project-workflow

{
  "packages.namespace": "@akson",         // Package namespace
  "package.manager": "pnpm"              // Package manager
}

makerkit-complete (MakerKit Projects)

{
  "dev.command": "pnpm dev",              // Development start command
  "dev.filter": "pnpm --filter web dev", // Filtered dev command
  "build.command": "pnpm build",         // Build command
  "db.start": "pnpm supabase:web:start", // Database start
  "db.reset": "pnpm supabase:web:reset", // Database reset
  "db.typegen": "pnpm supabase:web:typegen", // Type generation
  "package.build": "pnpm --filter @kit/ui build",
  "package.add": "pnpm --filter web add lodash",
  "package.manager": "pnpm",
  "package.filter": "pnpm --filter"
}

Configuration Best Practices

Project Type Detection

The CLI automatically detects your project type based on:

• Next.js: Presence of next dependency
• Monorepo: turbo dependency or workspaces in package.json
• Flutter: pubspec.yaml file
• Backend: express, fastify, or koa dependencies

Customizing Rules for Your Project

Essential Rules (Always Include)

{
  "rules": [
    { "id": "claude-essentials", "enabled": true },
    { "id": "code-standards", "enabled": true },
    { "id": "security-standards", "enabled": true }
  ]
}

For MakerKit Projects

{
  "rules": [
    // ... essential rules
    { "id": "makerkit-complete", "enabled": true }
  ]
}

For Projects with Shared Packages

{
  "rules": [
    // ... essential rules
    {
      "id": "project-workflow",
      "enabled": true,
      "variables": {
        "packages.namespace": "@your-org",
        "package.manager": "pnpm"
      }
    }
  ]
}

Migration from Older Versions

If you have an existing CLAUDE.md generated with older rules:

1. Backup your current CLAUDE.md: cp CLAUDE.md CLAUDE.md.backup
2. Initialize new rules: npx cortex-doc-standards rules init
3. Customize the configuration: Edit .cortex-doc-standards/rules.json
4. Regenerate: npx cortex-doc-standards generate
5. Compare and merge: Review any custom content from your backup

Troubleshooting

Common Issues

"No rules configuration found"

# Solution: Initialize rules first
npx cortex-doc-standards rules init

"Invalid configuration" errors

• Check JSON syntax: Ensure valid JSON in .cortex-doc-standards/rules.json
• Verify rule IDs: Use only built-in rule IDs listed above
• Check variable format: Ensure all variables are strings

"Unknown rule ID" warnings

• Update package: npm install @akson/cortex-doc-standards@latest
• Check spelling: Verify rule ID matches exactly (case-sensitive)

Variables not being replaced

• Check braces: Variables must use {variable.name} format
• Verify placement: Variables only work within rule templates
• Check scope: Ensure variable is defined for the specific rule

Setup & Configuration

cortex-doc-standards init --type <nextjs|flutter|backend|shopify|monorepo>
cortex-doc-standards config                    # Show current config
cortex-doc-standards health --verbose          # System health check

Validation & Quality

cortex-doc-standards validate                  # Validate all docs
cortex-doc-standards validate --file README.md # Single file
cortex-doc-standards validate --fix            # Auto-fix issues
cortex-doc-standards claude-check              # Claude AI standards check
cortex-doc-standards github-check              # GitHub Projects integration check

Templates & Generation

cortex-doc-standards templates                 # List available templates
cortex-doc-standards generate claude --project-name MyProject --output CLAUDE.md
cortex-doc-standards generate <template> --project-type nextjs

Reports & Analysis

cortex-doc-standards report --format table     # Human-readable report
cortex-doc-standards report --format json      # Machine-readable JSON
cortex-doc-standards naming --dry-run          # Preview naming fixes
cortex-doc-standards naming --fix              # Apply naming conventions

Project Integration

1. Initialize Documentation Standards

cd your-project/
cortex-doc-standards init --type nextjs
# Creates cortex-docs.config.json with project-specific rules

2. Configure Rules (cortex-docs.config.json)

{
  "name": "my-project",
  "type": "nextjs",
  "docsPath": "docs/",
  "claudePath": "CLAUDE.md",
  "rules": {
    "maxLines": 100,
    "minCodeBlockPercentage": 30,
    "requiredSections": ["Usage"],
    "blockedPatterns": [
      "This document provides",
      "Historical context",
      "Phase 1, Phase 2"
    ],
    "claudeEmojis": {
      "required": true,
      "validEmojis": ["🟣", "🟠"]
    },
    "enforcementLevel": "error"
  }
}

3. Add to CI/CD Pipeline

# .github/workflows/docs-quality.yml
name: Documentation Quality
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npx @akson/cortex-doc-standards validate
      - run: npx @akson/cortex-doc-standards naming --dry-run

4. Pre-commit Hook

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "cortex-doc-standards validate --fix"
    }
  }
}

Programmatic Usage

import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// Use CLI programmatically
const cli = new ConsolidatedCLI();
await cli.run();

Available Exports

// Main package
import { ConsolidatedCLI } from "@akson/cortex-doc-standards";

// CLI module
import { ConsolidatedCLI } from "@akson/cortex-doc-standards/cli";

// MCP server
import { DocStandardsMCPServer } from "@akson/cortex-doc-standards/mcp";

// Core validator
import { DocumentationValidator } from "@akson/cortex-doc-standards/core";

// Standards
import { GITHUB_PROJECTS_STANDARDS } from "@akson/cortex-doc-standards/standards";

Unified Rules Migration

The unified rules system eliminates fragmented rule definitions and provides a single source of truth for all documentation standards.

Key Changes

• One rule type – import UnifiedRule instead of legacy variants.
• One validator – use UnifiedDocumentationValidator or the createValidator() factory.
• Shared defaults – consume DEFAULT_UNIFIED_RULES for baseline configuration.
• Centralized blocked patterns – extend BASE_BLOCKED_PATTERNS rather than maintaining ad-hoc arrays.

import {
  UnifiedDocumentationValidator,
  UnifiedRule,
  createValidator,
  DEFAULT_UNIFIED_RULES,
  BASE_BLOCKED_PATTERNS,
} from '@akson/cortex-doc-standards';

const validator = createValidator('nextjs', {
  maxLines: 150,
  requiredSections: ['Custom Section'],
});

Migration Checklist

1. Update imports across projects to the unified exports shown above.
2. Replace old types (ValidationRule, DocumentationRules, etc.) with UnifiedRule.
3. Instantiate validators via UnifiedDocumentationValidator or createValidator().
4. Consolidate configuration using helpers such as mergeRules and getProjectRules.
5. Adopt common blocked patterns from BASE_BLOCKED_PATTERNS and extend only when necessary.

import { getProjectRules, mergeRules } from '@akson/cortex-doc-standards';

const baseRules = getProjectRules('monorepo');
const rules: UnifiedRule = mergeRules({
  maxLines: 180,
  requiredSections: ['Usage'],
}, baseRules);

const validator = new UnifiedDocumentationValidator(rules);

Rules System Reference

Quick Start

# Initialize rules configuration
npx @akson/cortex-doc-standards rules init --name "MyProject" --type nextjs

# Generate CLAUDE.md (standalone generator works without a build step)
npx @akson/cortex-doc-standards generate-claude generate --dry-run

# Validate configuration
npx @akson/cortex-doc-standards rules validate

Built-in Rule Catalog

| Rule ID | Description | Key Variables | | ---------------------------------- | -------------------------------------------------- | ------------------------------------------------------------ | | claude-prompting-fundamentals | AI interaction and communication standards | translation.function | | claude-development-workflow | Structured development process with Claude AI | lint.command, test.command, mobile.platform | | shared-packages | Governance for modifying Cortex shared packages | packages.namespace, packages.registry | | github-projects | GitHub Projects workflow standards | project.owner, project.repo | | security-standards | Security best practices & secret management | secrets.manager, auth.method, security.scanCommand | | testing-standards | Testing requirements and quality gates | coverage.unit, test.unit, test.e2e, test.integration | | makerkit-framework-integration | NEW MakerKit SaaS framework guidance | mobile.platform, mobile.commands, makerkit.location | | makerkit-package-discovery | NEW Component discovery using MCP server | Auto-configured | | makerkit-development-workflow | NEW MakerKit-specific development patterns | ui.library, auth.system, state.library | | makerkit-architecture-patterns | NEW Multi-tenant architecture guidance | Auto-configured | | makerkit-form-data-patterns | NEW Form handling with MakerKit components | Auto-configured |

Project templates automatically compose rule sets:

• Next.js / Backend – includes all core rules plus GitHub workflows.
• Monorepo – core rules + shared package governance.
• Flutter / Mobile – security + testing rules.
• Package / Library – minimal standards with publication guidance.
• MakerKit SaaS – complete framework integration with all MakerKit rules enabled.
• Cross-Platform – MakerKit web + Flutter mobile with shared backend patterns.

Configuration Schema

{
  "projectName": "MyProject",
  "projectType": "nextjs",
  "rules": [
    {
      "id": "shared-packages",
      "enabled": true,
      "variables": {
        "packages.namespace": "@akson",
        "packages.registry": "https://registry.npmjs.org"
      },
      "overrides": {
        "title": "Custom Title",
        "append": "Additional custom content"
      }
    }
  ],
  "globalVariables": {
    "project.name": "MyProject",
    "project.type": "nextjs"
  }
}

CLI Reference

# Discover rules
npx @akson/cortex-doc-standards rules list

# Initialize with explicit output path
npx @akson/cortex-doc-standards rules init \
  --name "MyApp" \
  --type backend \
  --output ./docs/rules.json

# Generate CLAUDE.md from a custom config
npx @akson/cortex-doc-standards rules generate \
  --config ./docs/rules.json \
  --output ./CLAUDE.md

# Validate or augment an existing configuration
npx @akson/cortex-doc-standards rules add-rule --id security-standards --enabled
npx @akson/cortex-doc-standards rules validate --config ./docs/rules.json

Advanced Usage

• Custom variables – supply project-specific data for templates.

  {
    "rules": [
      {
        "id": "testing-standards",
        "variables": {
          "test.unit": "vitest",
          "test.e2e": "playwright test",
          "coverage.unit": "90"
        }
      }
    ]
  }

• Rule overrides – tailor headings, append custom notes, or disable sections while staying within the unified schema.

• Factory helpers – createValidator(projectType, overrides) merges defaults with overrides and resolves variables before validation.

const validator = createValidator('package', {
  blockedPatterns: [...BASE_BLOCKED_PATTERNS, 'My legacy phrase'],
});

const results = await validator.validate('./docs');

Documentation Standards

This package helps enforce consistent documentation standards across Cortex projects:

Core Principles

• Clarity - Clear, concise documentation
• Consistency - Standardized formats and naming
• Maintainability - Rules-based generation and validation
• AI Integration - Claude AI workflow optimization

MCP Server Integration

The package includes an MCP (Model Context Protocol) server for Claude AI integration:

Starting the MCP Server

# Run the MCP server
npx cortex-doc-standards-mcp

MCP Tools Available

The MCP server provides tools for:

• Documentation validation
• Rules management
• Template generation
• Standards enforcement

Integration with Claude

Add the MCP server to your Claude configuration to access documentation tools directly in Claude conversations.

Configuration

The package uses a simple JSON-based configuration system:

Rules File Structure

{
  "version": "1.0.0",
  "rules": [
    // Your documentation rules here
  ],
  "templates": {
    // Template configurations
  }
}

TypeScript Types

interface RulesConfig {
  version: string;
  rules: DocumentationRule[];
  templates: Record<string, TemplateConfig>;
}

Version History

• 3.0.0 - Current version with CLI and MCP server
• 2.x.x - Legacy versions

Contributing

Part of the Cortex packages ecosystem. Contributions welcome!

License

MIT

Support

For support, please open an issue in the Cortex Packages repository.