Project Constraints Awareness

Purpose

This instruction teaches AI agents to proactively understand project constraints from configuration files BEFORE creating or modifying files, preventing wasted effort from constraint violations discovered during commit.

Core Principle

Read constraints first, apply them always, fail fast if uncertain.

Constraint Discovery Process

Before starting any file creation or modification task, agents should:

1. Read Pre-Commit Configuration

File: .pre-commit-config.yaml

Extract:

• Hook IDs and what they enforce
• File patterns they apply to
• Auto-fix capabilities
• Blocking vs. warning hooks

Example Analysis:

- repo: local
  hooks:
    - id: check-naming-conventions
      name: Check naming conventions
      entry: python scripts/check-naming-conventions.py
      language: system

Agent Understanding:

• "Files must follow naming conventions enforced by custom script"
• "Need to check scripts/check-naming-conventions.py for rules"
• "This is a blocking hook (will prevent commit)"

2. Read Linting Configurations

Files:

• .eslintrc, eslint.config.js - JavaScript/TypeScript rules
• .markdownlint.json - Markdown formatting rules
• .yamllint.yaml - YAML syntax rules
• .ansible-lint - Ansible playbook rules

Extract:

• Naming conventions (kebab-case, camelCase, PascalCase)
• Formatting rules (indentation, line length, quotes)
• Required metadata (frontmatter fields)
• Disallowed patterns

Example Analysis:

{
  "MD060/table-column-style": {
    "style": "compact"
  },
  "MD040/fenced-code-language": true
}

Agent Understanding:

• "Markdown tables must use compact style (pipes aligned)"
• "All fenced code blocks must specify a language"
• "Before creating markdown, ensure code blocks have language tags"

3. Read CI/CD Workflows

Files: .github/workflows/*.yml

Extract:

• Required checks (linting, testing, building)
• Runner requirements (self-hosted, GitHub-hosted)
• NPM registry configurations
• Required secrets/environment variables
• Allowed GitHub Actions sources

Example Analysis:

jobs:
  build:
    runs-on: { group: nomad-epic-actions-runner } # REQUIRED
    env:
      NPM_CONFIG_REGISTRY: https://edgeinternal1uhg.optum.com/artifactory/api/npm/glb-npm-npmjsorg-rem/

Agent Understanding:

• "Must use self-hosted Nomad runners (NOT ubuntu-latest)"
• "Must use internal JFrog Artifactory for npm (NOT public npmjs.org)"
• "Workflows must authenticate with EOA_JFROG_SAAS_NPM_TOKEN"

4. Read Project Documentation

Files:

• CLAUDE.md - Repository-specific agent instructions
• AGENTS.md - Agent usage guidelines
• CONTRIBUTING.md - Contribution guidelines
• README.md - Project overview and conventions

Extract:

• Naming patterns (e.g., "lowercase kebab-case filenames")
• Required metadata (YAML frontmatter)
• Architectural patterns (e.g., "Diataxis documentation structure")
• Technology stack constraints

5. Check Custom Scripts

Files: scripts/check-*.js, scripts/validate-*.js

Extract:

• Custom validation logic
• Schema requirements
• Quality thresholds
• Naming conventions enforcement

Application Rules

Before Creating Files

1. Check naming conventions:

   • Apply lowercase kebab-case (unless exceptions listed)
   • Avoid capital letters (except README, LICENSE, CHANGELOG, etc.)
   • Use appropriate extensions (.md, .js, .yml, not .MD, .JS, .YML)

2. Apply metadata requirements:

   • Add complete YAML frontmatter to assets
   • Include required fields (version, kind, id, title, description, owner, etc.)
   • Set appropriate lifecycle_status and last_reviewed date

3. Follow formatting rules:

   • Use correct indentation (spaces vs. tabs per config)
   • Apply line length limits
   • Use correct quote style (single vs. double)
   • Add language tags to code blocks

Before Committing

1. Validate against constraints:

   • Run linters mentally (check quote style, indentation, naming)
   • Verify metadata completeness
   • Check file patterns match conventions

2. Predict hook failures:

   • "Will this fail check-naming-conventions?" (capital letters?)
   • "Will this fail markdownlint-cli?" (code blocks without language?)
   • "Will this fail markdownlint-cli?" (table formatting?)
   • "Will this fail eslint?" (quote style, template literals?)

3. Pre-emptively fix issues:

   • Convert filenames to lowercase before creation
   • Add language tags to code blocks during writing
   • Format tables using compact style
   • Use single quotes in JavaScript (if that's the rule)

Integration with Kratos Memory

Store learned constraints in Kratos for persistence across sessions:

# Store constraint summary
mcp__kratos__memory_save \
  --summary "Project naming conventions: lowercase kebab-case, no capitals except README/LICENSE/CHANGELOG/AGENTS/SKILL/Makefile" \
  --text "Enforced by .pre-commit-config.yaml check-naming-conventions hook. Examples: use 'issue-preparation.md' not 'ISSUE_PREPARATION.md', use 'mcp-config.js' not 'MCPConfig.js'" \
  --tags "constraints,naming,pre-commit" \
  --importance 5

# Store linting rules
mcp__kratos__memory_save \
  --summary "Markdown linting rules: code blocks need language, tables use compact style" \
  --text "MD040: All fenced code blocks must specify language (```javascript not ```). MD060: Tables use compact style with aligned pipes." \
  --tags "constraints,markdown,linting" \
  --importance 4

Example Workflow

Scenario: Creating a new markdown file

❌ Old Way (Reactive):

1. Agent creates NEW_FEATURE.md
2. Pre-commit hook fails: "CAPITAL LETTER in filename"
3. Agent renames to new-feature.md
4. Pre-commit hook fails: "Code blocks need language"
5. Agent adds language tags
6. Pre-commit hook fails: "Table formatting incorrect"
7. Agent fixes table formatting
8. Finally commits (3 failures, wasted time)

✅ New Way (Proactive):

1. Agent reads .pre-commit-config.yaml
2. Understands: "lowercase kebab-case, code blocks need language, tables use compact style"
3. Agent creates new-feature.md with:
   • Lowercase kebab-case name
   • Language tags on all code blocks: ```javascript
   • Tables formatted with compact style
4. Commits successfully (0 failures, no wasted time)

Implementation Checklist

Before starting any task that creates or modifies files:

• Read .pre-commit-config.yaml - understand hooks and what they enforce
• Read .markdownlint.json (or equivalent) - understand formatting rules
• Read eslint.config.js (or equivalent) - understand code style
• Read .github/workflows/*.yml - understand CI/CD requirements
• Read CLAUDE.md / AGENTS.md - understand project-specific conventions
• Check Kratos memory for stored constraints
• Mentally validate planned changes against constraints
• Create/modify files following all discovered rules
• Predict and prevent hook failures before committing

Benefits

1. Efficiency: No wasted time fixing preventable constraint violations
2. Learning: Agents understand "why" rules exist, not just "what" they are
3. Consistency: All created files follow project patterns from the start
4. Automation: Constraints stored in memory persist across sessions
5. Feedback Loop: When new constraints are added, agents discover and adapt

Future Enhancements

1. Auto-generate constraint summaries:

   • Parse .pre-commit-config.yaml and create human-readable constraint list
   • Store in .claude/constraints.md for easy reference

2. Constraint validation tool:

   • CLI command: otc-awesome-llm validate constraints <file>
   • Checks file against all known constraints before commit

3. Constraint conflict detection:

   • Detect when two configs have conflicting rules
   • Alert user to resolve before agent wastes time

4. Meta-configuration system:

   • Feedback loop where constraint violations update configs
   • Self-refining rules based on real usage patterns

Related Documentation

• Pre-commit Configuration
• Markdownlint Configuration
• ESLint Configuration
• CLAUDE.md - Repository instructions
• Kratos Memory Usage

Notes

This instruction represents a paradigm shift from reactive constraint handling to proactive constraint awareness. By reading and understanding project constraints BEFORE creating files, agents save time, reduce frustration, and produce higher-quality outputs that follow project standards from the first attempt.