*******************************************************************************
002. Template-Based Settings Distribution
*******************************************************************************

Status
===============================================================================

Accepted

Context
===============================================================================

AI agent settings files (like Claude Code's ``settings.json``) contain both 
static configuration and dynamic hook configurations that reference script paths. 
This creates a coordination problem between distributed configurations and actual 
script locations across different deployment environments.

Key challenges include:

* Hook configurations must reference script paths that exist in target environments
* Settings files are inherently project-specific (file paths, project-specific hooks)
* Base settings need to be consistent while allowing project customization
* Must avoid duplicating Copier's templating functionality
* Need to maintain compatibility with existing AI tool expectations

Several approaches were considered:

**Direct Distribution**: Distribute complete ``settings.json`` files with hardcoded paths.

**Configuration Merging**: Use git diff-based algorithms similar to Copier for 
merging base and project-specific settings.

**Custom CLI Renderer**: Use Jinja2 templates with custom CLI tooling for 
settings generation and local override support.

**Copier Template Integration**: Transform agents-common into a Copier template 
that generates tool configurations from structured data sources.

Decision
===============================================================================

Implement a hybrid approach combining Copier template distribution for base 
configuration templates with ``agentsmgr`` tool for dynamic content generation 
directly in downstream projects from structured data sources.

The approach includes:

**Data-Driven Source Structure**:
- ``data/`` directory contains structured sources (TOML command definitions, 
  agent configurations, hook scripts, tool-specific Jinja2 templates)
- ``agentsmgr populate`` generates content directly in downstream projects
- Single source of truth maintained in structured, tool-agnostic format

**Minimal Copier Template** (``template/.auxiliary/configuration/``):
- Contains base configuration templates (settings.json.jinja, mcp-servers.json.jinja)
- Provides directory structure with .gitignore files for generated content
- README files indicating dynamic generation via agentsmgr
- Standard Copier template structure for base distribution

**Dynamic Content Generation**:
- ``agentsmgr populate --source=agents-common@tag`` generates commands, agents, scripts
- Content generated directly in downstream projects, not committed to version control
- Tool-specific formats handled at generation time from common data sources
- Configuration detected from Copier answers files or defaults

Alternatives
===============================================================================

**Direct Distribution** was rejected because:
- Cannot handle path coordination between different deployment environments
- Requires hardcoded paths that break across different project structures  
- No mechanism for project-specific customization
- Creates maintenance burden for path updates

**Configuration Merging** was rejected because:
- Adds significant complexity with git diff algorithms
- Difficult to handle conflicts between base and project settings
- More complex than the coordination problem warrants
- Increases maintenance overhead for merge conflict resolution

**Pure Copier Template** was rejected because:
- Generated artifacts committed to version control create repository noise
- Command changes require template generation, commit, tag, and update cycle
- Slower iteration velocity for dynamic content like commands and agents
- Template repository grows with generated content rather than source data

**Custom CLI Renderer Only** was rejected because:
- Base configuration templates benefit from Copier's proven distribution mechanisms
- Projects lose standard multi-template workflow patterns
- Does not leverage existing Copier infrastructure for settings and structure

Consequences
===============================================================================

**Positive Consequences:**

* **Faster Iteration Cycle**: Command changes don't require template commits, tags, or releases
* **Repository Efficiency**: No generated artifacts committed, cleaner git history
* **Proven Base Distribution**: Settings templates use Copier's mature mechanisms
* **True Tool Portability**: ``agentsmgr`` works with any data source, not repository-specific
* **Minimal Commit Noise**: Generated content ignored via .gitignore in downstream projects
* **Clean Separation**: Static base templates vs. dynamic generated content
* **Multi-Tool Scaling**: Single data source generates configurations for multiple AI tools

**Negative Consequences:**

* **Tool Installation Requirement**: Projects need ``agentsmgr`` available for setup
* **Network Dependency**: Requires access to agents-common repository for content generation
* **Configuration Detection**: Additional logic needed to detect project configuration from Copier answers

**Neutral Consequences:**

* **Hybrid Workflow**: Projects use both Copier updates and agentsmgr commands for different content types
* **Repository Structure Change**: Requires migration from ``products/`` to ``data/`` + minimal ``template/``
* **Generated Content Management**: Downstream projects manage generated vs. custom content boundaries