Foundation

Shared development processes and practices for consistent, high-quality software development.

What is Foundation?

Foundation is a collection of generalized, composable development processes that can be shared across multiple repositories. It includes:

• Development Workflow - Git branch strategy, PR process, code review guidelines, Feature Unit workflow, release orchestration
• Code Conventions - Naming patterns, style guides for TypeScript, SQL, YAML, Shell
• Documentation Standards - Structure, formatting, and writing style
• Security Practices - Pre-commit audits, credential management, security rules
• Agent Instructions - Cursor rules and commands for AI coding assistants
• Configuration System - Flexible YAML-based configuration for repo-specific customization
• Strategy Frameworks - Product discovery, competitive analysis, partnership evaluation (optional)
• Validation Systems - Spec compliance validation, documentation dependency tracking (optional)
• Tooling - Secrets management, environment management, agent setup (optional)
• Integration Scripts - Easy adoption and synchronization

Key Features

✅ Configurable - Adapt to your project's needs via foundation_config.yaml
✅ Composable - Pick and choose what you need
✅ Shareable - Use across multiple repositories via git submodules
✅ Agent-Friendly - Designed for AI coding assistants
✅ Maintainable - Single source of truth for best practices

Quick Start

Installation

1. Install foundation as a git submodule:

# From your repository root
./path/to/foundation/scripts/install_foundation.sh ../foundation

# Or from a remote repository
./path/to/foundation/scripts/install_foundation.sh https://github.com/user/foundation.git

2. Customize configuration:

# Edit foundation_config.yaml to match your project
vim foundation_config.yaml

3. Validate setup:

./foundation/scripts/validate-setup.sh

Basic Usage

Development Workflow:

# Create a feature branch (worktree recommended)
./foundation/development/worktree-setup.sh my-feature

# Make changes, commit, push
git add .
git commit -m "feat: add new feature"
git push

Code Review:

• Follow PR process in foundation/development/pr-process.md
• Use code conventions in foundation/conventions/code-conventions.md

Feature Units (if enabled):

# Create a new Feature Unit
# (uses interactive spec creation via agent)
# Follow workflow in foundation/development/feature_unit_workflow.md

Security:

# Run pre-commit security audit
./foundation/security/pre_commit_audit.sh

Setup Agent Instructions:

# Install Cursor rules and commands as symlinks
./foundation/scripts/setup_cursor_rules.sh

Directory Structure

foundation/
├── agent_instructions/   # AI agent instructions (Cursor rules & commands)
│   ├── cursor_rules/     # Generic Cursor rules
│   ├── cursor_commands/  # Generic Cursor commands
│   └── README.md
├── development/          # Development workflow and branch strategy
│   ├── workflow.md
│   ├── branch-strategy.md
│   ├── pr-process.md
│   ├── feature_unit_workflow.md
│   ├── release_workflow.md
│   ├── worktree-setup.sh
│   └── templates/        # Feature Unit templates
├── conventions/          # Code and documentation conventions
│   ├── code-conventions.md
│   ├── documentation-standards.md
│   └── naming-patterns.yaml
├── security/             # Security practices
│   ├── security-rules.md
│   ├── pre-commit-audit.sh
│   └── credential-management.md
├── strategy/             # Strategy evaluation frameworks (optional)
│   ├── README.md
│   └── [analysis templates]
├── tooling/              # Development tooling (optional)
│   └── README.md
├── validation/           # Validation systems (optional)
│   └── README.md
├── config/               # Configuration system
│   ├── foundation_config.yaml
│   └── repo_adapters/
│       ├── template.yaml
│       └── personal.yaml
├── scripts/              # Integration and utility scripts
│   ├── install_foundation.sh
│   ├── sync_foundation.sh
│   ├── validate_setup.sh
│   └── setup_cursor_rules.sh
└── README.md

Configuration

Foundation is configured via foundation_config.yaml in your repository root.

Example configuration:

repository:
  name: "my-project"
  type: "application"

development:
  branch_strategy:
    feature_prefix: "feature"
    naming_pattern: "{prefix}/{id}-{description}"
  workflow:
    use_worktrees: true

conventions:
  typescript:
    files: "snake_case"
    string_quotes: "double"

security:
  enabled: true
  pre_commit_audit:
    enabled: true
    protected_paths:
      - "docs/private/"
      - ".env*"

See foundation/config/foundation_config.yaml for all available options.

Sharing Across Repositories

Using Git Submodules (Recommended)

Setup:

# In foundation repository
cd ~/Projects/foundation
git init
# ... add foundation content ...
git add .
git commit -m "Initial foundation"
git remote add origin <remote-url>
git push -u origin main

# In consuming repository
cd ~/Projects/my-project
git submodule add <remote-url> foundation

Sync changes:

# In consuming repository
cd foundation
git pull origin main
cd ..
git add foundation
git commit -m "Update foundation"

Or use the sync script:

./foundation/scripts/sync-foundation.sh

Agent-Editable Shared Processes

When agents make changes to foundation from any consuming repository:

1. Changes are made in the submodule
2. Commit and push from the submodule
3. Other repositories pull updates via git submodule update --remote foundation
4. Or use ./foundation/scripts/sync-foundation.sh

Customization

Repository-Specific Overrides

Create a repository adapter in foundation/config/repo_adapters/:

# my-repo.yaml
repo_name: "my-repo"
extends: "template.yaml"

# Override specific settings
conventions:
  typescript:
    files: "kebab-case"  # Different from foundation default

security:
  pre_commit_audit:
    protected_paths:
      - "private/"  # Custom protected path

Local Overrides

For local development overrides (not committed):

# foundation-config.local.yaml (add to .gitignore)
development:
  workflow:
    use_worktrees: false  # Override for this machine only

Documentation

• Development Workflow - Git workflow, branching, PRs
• Feature Unit Workflow - Spec-first development with Feature Units
• Release Workflow - Release orchestration and coordination
• Code Conventions - Style guides for all languages
• Documentation Standards - Doc structure and style
• Security Rules - Security best practices
• Agent Instructions - Cursor rules and commands for AI assistants
• Strategy Frameworks - Product discovery and competitive analysis (optional)
• Tooling - Development tooling configuration (optional)
• Validation Systems - Spec compliance and doc dependency validation (optional)
• Contributing - How to contribute to foundation

Use Cases

Scenario 1: Multiple Projects with Similar Tech Stack

Use foundation to share conventions across all projects:

• Same TypeScript conventions
• Same PR process
• Same testing standards
• Repo-specific configuration for differences

Scenario 2: Personal Repository + Work Repository

Share common practices while keeping repo-specific content separate:

• Foundation: Generic workflow, conventions
• Work repo: Company-specific processes
• Personal repo: Personal project patterns

Scenario 3: Team Onboarding

New team members get consistent documentation:

• Same workflow in all repositories
• Same conventions to learn once
• Same tooling and scripts

Maintenance

Updating Foundation

1. Make changes in the foundation repository
2. Commit and push
3. In consuming repositories:

git submodule update --remote foundation
git add foundation
git commit -m "Update foundation"

Version Management

Foundation uses semantic versioning via git tags:

# In foundation repository
git tag v1.0.0
git push --tags

# In consuming repository
cd foundation
git checkout v1.0.0

Contributing

See CONTRIBUTING.md for guidelines on contributing to foundation.

Migration

See MIGRATION.md for migrating from project-specific processes to foundation.

FAQ

Q: Should I use submodules or symlinks?
A: Submodules for production use (version control, team collaboration). Symlinks for local development only.

Q: Can I modify foundation files in my repository?
A: Yes, but prefer configuration over modification. If you need to modify, consider contributing back to foundation.

Q: How do I handle conflicts when updating foundation?
A: Same as any git submodule conflict. Resolve conflicts, commit, and push.

Q: Can I use foundation without all components?
A: Yes, enable/disable components in foundation_config.yaml. Most components are optional (Feature Units, strategy, validation, tooling).

Q: What are Feature Units?
A: Feature Units are a spec-first development workflow where changes are fully specified before implementation. See foundation/development/feature_unit_workflow.md.

Q: How do I set up agent instructions?
A: Run ./foundation/scripts/setup_cursor_rules.sh to create symlinks from .cursor/ to foundation rules and commands. See foundation/agent_instructions/README.md.

Support

For issues or questions:

• Check existing documentation
• Review foundation_config.yaml for configuration options
• Create an issue in the foundation repository

License

MIT License

Copyright (c) 2025 Mark Hendrickson

See LICENSE for full license text.