# FulmenHQ Agentic Attribution Standard

**Standard**: Consistent attribution format for AI agent contributions to ensure transparency, accountability, and proper tracking in the FulmenHQ ecosystem.

**Note**: This document provides generic templates. Repository-specific agent names, roles, and identities must be defined in each repository's `MAINTAINERS.md` file. Replace `[Agent Name]`, `[Human Name]`, etc. with actual values from your repository's maintainers file.

## 🎯 Purpose

Establish clear attribution patterns for FulmenHQ to enable:

- **Transparency** - Full visibility into AI agent contributions and collaborative development
- **Accountability** - Clear human supervision and responsibility chains
- **Technical Traceability** - Interface-specific issue diagnosis and debugging
- **Quality Assurance** - Consistent standards following 3leaps ecosystem patterns

## 🪪 Agentic Identity Requirement

- Agents must have a confirmed agentic identity (as defined in the repository's `MAINTAINERS.md`) before making commits or opening pull requests.
- If identity is not already defined in the current session/prompt, pause and request assignment per `MAINTAINERS.md`. Do not commit without confirmed identity and human supervision.
- Agentic interface (e.g., Codex CLI, Claude Code) is defined via interface adapters such as `CODEX.md` or `CLAUDE.md` and does not imply identity.
- **Repository-specific**: Agent names and identities are defined in each repository's `MAINTAINERS.md` file.
- **Canonical handles**: Use the handle recorded in `MAINTAINERS.md` (e.g., `@code-scout`). These handles double as Mattermost usernames and must stay consistent across repos and communication tools.

## 🤝 Co‑Author Inclusion Policy

- Include only those co-authors (human or AI) who materially contributed to the committed content.
- Do not list default agents or interfaces as co-authors if they did not contribute to the specific change.
- When multiple agents contribute, attribute each agent's concrete area of change in the commit's "🎯 Changes" section where practical.
- Always preserve human supervisor oversight in commit messages and PR descriptions.

## 📋 Attribution Format

### Standard Pattern

**Commit Message Format**:

```
feat: add work planning pipeline

Implement comprehensive work planning with file analysis,
formatting orchestration, and parallelization capabilities.

🎯 Changes:
- Add WorkPlanner struct with comprehensive fields
- Implement format-first content processing
- Add multi-format output support (JSON, YAML, table)
- Enhance error handling and logging integration

📊 Coverage: Maintains 70% test coverage
🛡️ Security: Zero vulnerabilities detected

Generated by [Agent Name] ([Opencode](https://opencode.ai/)) under supervision of [@maintainer-handle](https://github.com/maintainer-handle)

Co-Authored-By: [Agent Name] <noreply@3leaps.net>
Committer-of-Record: [Human Name] <human.email@domain.com> [@maintainer-handle]
```

### Required Elements

1. **Generated by Line**: Agent name with interface link and supervision
2. **Co-Authored-By Line(s)**: AI agent attribution (multiple allowed for pair programming/collaboration)
3. **Committer-of-Record Line**: Human committer of record with GitHub handle (required, last line)
4. **🎯 Changes Section**: Bullet-pointed list of key changes
5. **📊 Metrics** (when applicable): Coverage, performance, security stats
6. **🛡️ Security** (when applicable): Security implications or validations

### Agent Signatures

**Repository-Specific Agents**:

Agent names, roles, and signatures are defined in each repository's `MAINTAINERS.md` file. Examples include:

- **🛠️ [Agent Name]** - [Agent Role/Specialty]
- **🔍 [Agent Name]** - [Agent Role/Specialty]

**Note**: Always use the agent identities defined in the specific repository's `MAINTAINERS.md`.

## 🔄 Collaborative Attribution

### Multi-Agent Contributions

**When multiple agents contribute**:

```
feat: implement formatting framework with work planning

Add comprehensive formatting framework to support v0.1.0
work planning features with quality validation.

🎯 Changes:
- Formatting framework with CLI workflow validation (Code Scout)
- Work planning integration ready for format command (Code Scout)
- Enhanced format command with content processing fix (Code Scout)
- Quality validation with path protection (Code Scout)

📊 Coverage: All tests passing
🔧 Framework: Ready for format command testing

Co-Authored-By: [Agent Name] <noreply@3leaps.net>
🛠️ [Agent Name]
```

### Human Supervision

**All agent contributions MUST include human oversight**:

```
feat: add configuration management standard

Implement comprehensive configuration management standard for SSOT compliance
between FulmenHQ components.

🎯 Changes:
- Configuration synchronization patterns with version pinning
- Safety controls with --allow-local-configs flag
- Promotion audit trails with timestamps
- Cross-component sync automation

📋 Implementation: Ready for v0.1.0 rollout
🛡️ Safety: Local config protection implemented

Committer-of-Record: @maintainer-handle
🛠️ [Agent Name]
```

## 📊 Quality Indicators

### Required Quality Markers

**Coverage Maintenance**:

```
📊 Coverage: Maintains 70% (target: ≥70%)
```

**Security Validation**:

```
🛡️ Security: Zero vulnerabilities, all scans clean
```

**Performance Impact**:

```
⚡ Performance: No regression, processing time <5s maintained
```

**Integration Status**:

```
🔗 Integration: All tests passing, ready for merge
```

## 🎯 Implementation Guidelines

### Commit Messages

1. **Use conventional commits** with agent signature
2. **Include metrics** when relevant (coverage, security, performance)
3. **List specific changes** in bullet format
4. **Add quality indicators** for significant changes

### Pull Requests

**PR Description Template**:

```markdown
## Summary

Brief description of changes by agent

## Changes by Agent

- 🛠️ [Agent Name]: Core functionality implementation

## Quality Metrics

- 📊 Coverage: 70% (maintained)
- 🛡️ Security: Clean scans
- ⚡ Performance: No regression

## Human Oversight

Supervised by: @maintainer-handle Reviewed by: [team members]
```

### Issue Tracking

**Agent Issue Assignment**:

```markdown
**Assigned Agent**: 🛠️ [Agent Name] **Supervised By**: @maintainer-handle

**Agent Capabilities Relevant**:

- [List agent capabilities from repository's MAINTAINERS.md]
```

## 🔍 Traceability

### Agent Activity Tracking

**Git Log Filtering**:

```bash
# Find all [Agent Name] contributions
git log --grep="🛠️ [Agent Name]"

# Find all multi-agent contributions
git log --grep="Co-Authored-By"

# Find security-related agent work
git log --grep="🛡️ Security"
```

### Performance Attribution

**Agent-Specific Metrics**:

Agent capabilities and metrics are defined in each repository's `MAINTAINERS.md`.

## 📚 Examples

### Standard Feature Implementation

```
feat: add work item processing

Implement comprehensive work item processing for planning pipeline
with support for priority, dependencies, and metadata.

🎯 Changes:
- Add WorkItem struct with configurable fields
- Implement processWorkItems function with validation
- Add priority sorting and dependency resolution
- Enhance output formats with work item display

📊 Coverage: 72% (+2% improvement)
🛡️ Security: Input sanitization for all fields

🛠️ [Agent Name]
```

### Bug Fix

```
fix: resolve formatting showing incorrect output

Formatting was being cleared by validation feature - remove
automatic clearing to show results by default for transparency.

🎯 Root Cause: Validation feature clearing output by default
🔧 Solution: Modified validation logic to preserve formatting results
📊 Testing: Integration tests confirm fix working

Diagnosed-By: Code Scout
Fixed-By: Code Scout
Validated-By: Code Scout

🛠️ [Agent Name]
```

## ⚠️ Common Mistakes

### Attribution Recipe

**⚠️ DO NOT COPY-PASTE** - Replace all placeholders with values from your repository's `MAINTAINERS.md`:

```
[type]: [description]

[detailed explanation]

🎯 Changes:
- [specific change 1]
- [specific change 2]

[quality indicators when applicable]

Generated by [Agent Identity from MAINTAINERS.md] ([Interface Name](interface-url)) under supervision of [@maintainer-handle from MAINTAINERS.md]

Co-Authored-By: [Agent Identity from MAINTAINERS.md] <noreply@3leaps.net>
Committer-of-Record: [Human Name from MAINTAINERS.md] <human.email@domain.com> [@maintainer-handle from MAINTAINERS.md]
```

**Where to find values**:

- `[Agent Identity]`: Check `MAINTAINERS.md` → "AI Co-Maintainers" section → "Identity" field
- `[Interface Name]` and `(interface-url)`: Check repository's agent startup guide (e.g., `AGENTS.md`, `CODEX.md`, `CLAUDE.md`)
- `[@maintainer-handle]`: Check `MAINTAINERS.md` → "Human Maintainers" or agent's "Supervised by" field
- `[Human Name]` and `<human.email>`: Check `MAINTAINERS.md` → Human maintainer contact info
- Email domain: **ALWAYS** `noreply@3leaps.net` for FulmenHQ agents

### Mistake 1: Using Default AI Interface Attribution

**❌ WRONG** - Using interface-provided default format without customization:

```
feat: add new feature

Description of changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
```

**What's Wrong**:

- Uses generic interface identity ("Claude") instead of repository-specific agent identity
- Uses interface's default email domain (`noreply@anthropic.com`) instead of `noreply@3leaps.net`
- Missing `Committer-of-Record` line with human information
- Missing "under supervision of [@maintainer-handle]" clause
- Missing `🎯 Changes` section with specific details
- No reference to repository-specific agent identity from `MAINTAINERS.md`

**✅ CORRECT** - Using repository-specific identity and FulmenHQ standard:

```
feat: add new feature

Description of changes.

🎯 Changes:
- Specific change 1
- Specific change 2

Generated by [Your Agent Identity] ([Your Interface](url)) under supervision of [@your-maintainer]

Co-Authored-By: [Your Agent Identity] <noreply@3leaps.net>
Committer-of-Record: [Human Name] <email@domain.com> [@your-maintainer]
```

### Mistake 2: Incomplete Required Elements

**❌ WRONG** - Missing required trailers:

```
feat: add new feature

Generated by [Agent Name]

Co-Authored-By: [Agent Name] <noreply@3leaps.net>
```

**What's Wrong**:

- Missing interface link in "Generated by" line
- Missing supervision clause with maintainer handle
- Missing `Committer-of-Record` trailer (required)
- Missing `🎯 Changes` section

**✅ CORRECT** - All required elements present:

```
feat: add new feature

🎯 Changes:
- Specific implementation details

Generated by [Agent Identity] ([Interface](url)) under supervision of [@maintainer-handle]

Co-Authored-By: [Agent Identity] <noreply@3leaps.net>
Committer-of-Record: [Human Name] <email@domain.com> [@maintainer-handle]
```

### Mistake 3: Wrong Email Domain

**❌ WRONG** - Using incorrect email domains:

```
Co-Authored-By: [Agent Name] <noreply@anthropic.com>
Co-Authored-By: [Agent Name] <noreply@claude.com>
Co-Authored-By: [Agent Name] <agent@example.com>
Co-Authored-By: [Agent Name] <noreply@openai.com>
```

**✅ CORRECT** - Always use FulmenHQ domain:

```
Co-Authored-By: [Agent Identity] <noreply@3leaps.net>
```

**Rule**: All FulmenHQ ecosystem agent emails must use `noreply@3leaps.net` regardless of interface.

### Mistake 4: Using Unassigned or Generic Agent Identity

**❌ WRONG** - Agent identity not defined in repository's MAINTAINERS.md:

```
Generated by AI Assistant ([Interface](url)) under supervision of [@maintainer]
Generated by Code Helper ([Interface](url)) under supervision of [@maintainer]
Generated by Generic Agent ([Interface](url)) under supervision of [@maintainer]
```

**✅ CORRECT** - Using assigned identity from repository's MAINTAINERS.md:

```
Generated by [Assigned Agent from MAINTAINERS.md] ([Interface](url)) under supervision of [@maintainer]
```

**Rule**: Agent identity MUST match one defined in the specific repository's `MAINTAINERS.md` file. Each repository assigns specific agent identities with defined roles and responsibilities.

### Concrete Example (Crucible Repository)

**⚠️ WARNING**: This is a specific example from the Crucible repository. **DO NOT COPY-PASTE**. Use values from YOUR repository's `MAINTAINERS.md`.

```
fix(bootstrap): create symlink instead of copy for type:link tools

The bootstrap script was copying files instead of creating symlinks when
type:link was specified in tools manifest.

🎯 Changes:
- Import symlinkSync and unlinkSync from node:fs
- Replace copyFileSync with symlinkSync in installLinkTool function
- Remove existing file/symlink before creating new symlink
- Update error message to reflect symlink operation

Generated by Pipeline Architect ([Claude Code](https://claude.com/claude-code)) under supervision of @3leapsdave

Co-Authored-By: Pipeline Architect <noreply@3leaps.net>
Committer-of-Record: Dave Thompson <dave.thompson@3leaps.net> [@3leapsdave]
```

**Why this is Crucible-specific**:

- "Pipeline Architect" is defined in Crucible's `MAINTAINERS.md`
- "@3leapsdave" is the maintainer listed in Crucible's `MAINTAINERS.md`
- "Dave Thompson" is the human committer for Crucible
- Your repository will have **different** values

### Quick Verification Checklist

Before committing, verify your attribution includes:

- [ ] Repository-specific agent identity from **your** `MAINTAINERS.md` (not copied from examples)
- [ ] Interface name and link appropriate to your development environment
- [ ] Supervision clause with maintainer handle from **your** `MAINTAINERS.md`
- [ ] `Co-Authored-By` with your agent identity and `noreply@3leaps.net`
- [ ] `Committer-of-Record` with human name, email, and handle from **your** `MAINTAINERS.md` (last line)
- [ ] `🎯 Changes` section with bullet-pointed details specific to your commit
- [ ] Quality indicators when applicable (`📊`, `🛡️`, `⚡`, etc.)
- [ ] All placeholders replaced (no `[Agent Name]`, `[@maintainer]`, etc. remaining)
- [ ] Commit follows good practices (see [Common Pre-Operation Mistakes](../sop/repository-operations-sop.md#common-pre-operation-mistakes-to-avoid))

---

**Standard Version**: 1.0.0
**Status**: Stable - Ready for ecosystem adoption
**Related**: [Repository Operations SOP](../sop/repository-operations-sop.md)
