[FEATURE] ship a first-party AI agent attribution instruction profile

[yogurtearl]

Decision requested

Please accept a small, first-class attribution feature for APM: ship a first-party attribution instruction package that lets teams define AI agent work-product attribution once and have APM deploy it to each supported agent harness through the existing install and compile pipeline.

This issue intentionally proposes an accepted-MVP shape, not an open design exploration.

Suggested triage:

• Decision: accept
• Labels: theme/governance, area/enterprise, area/multi-target, type/feature, status/accepted, priority/high
• Milestone: next minor

Summary

Enterprises need consistent, reportable metadata when AI coding agents create or materially modify work products across heterogeneous development systems.

The target systems vary by organization. Some teams use GitHub, others use GitLab, Azure DevOps, Bitbucket, or internal code hosts. Some use Jira, others use Linear, Azure Boards, GitHub Issues, GitLab Issues, or internal work trackers. The attribution convention should therefore describe generic work-product types and metadata keys, then let each downstream system map those keys to its native surface.

APM is the right layer because it is the package manager for agent context. Instead of asking each repository to hand-copy attribution prose into .github/, .claude/, .cursor/, AGENTS.md, CLAUDE.md, and future target locations, APM should provide a first-party attribution profile that is installed once and projected to all active agent targets.

User need

As an enterprise platform owner, I want to install one APM-managed attribution profile so every supported agent harness receives consistent instructions to self-identify work products.

As a governance and reporting owner, I want agent-created or agent-modified artifacts to carry stable, system-agnostic metadata so reporting tools can measure agent involvement by repository, team, agent, role, work-product type, and source system.

As a repository maintainer, I want this to use the package-manager workflow I already expect from APM: add a package, run install/compile, review the generated diff, and commit it.

Proposed accepted design

1. Model attribution as a first-party instruction package, not a new primitive type

Add a first-party package under the APM repo, for example:

packages/agent-attribution/
  apm.yml
  README.md
  .apm/instructions/agent-attribution.instructions.md

The package contains one normal instruction primitive. No new top-level CLI command, no new dispatcher, no new manifest type, and no target-specific hand-authored output files are required for the MVP.

A representative source instruction:

---
description: Require AI agents to self-identify development work products.
---

# AI agent work-product attribution

When you create, modify, review, autofix, triage, or summarize development work products, identify agent involvement using the metadata below.

These instructions apply to work products in code hosts, version control systems, work trackers, documentation systems, and CI/CD systems. Examples include pull requests, merge requests, commits, reviews, issues, tickets, work items, generated files, release notes, build logs, and CI artifacts.

Use the generic metadata vocabulary below even when the underlying system uses different names.

## Required attribution fields

- AI-Agent: <agent-name>
- AI-Agent-Surface: <cloud|ide|review|ci|server>
- AI-Agent-Role: <author|reviewer|autofix|triage|summarizer>
- AI-Agent-Run: <url-or-id-or-unknown>
- AI-Agent-Initiated-By: <human-user-or-unknown>
- AI-Agent-Source-Work-Item: <url-or-key-or-unknown>

## Change requests

For every pull request, merge request, change request, or equivalent artifact you create or materially modify:

- add system-native labels, tags, topics, or fields when permissions allow
- preserve or add the hidden metadata block below in the description/body when the system supports free-form markdown or text
- if the system does not support hidden comments, add the same key/value pairs to the most appropriate native metadata surface

Recommended labels or tags:

- ai-agent
- agent-<agent-name>
- agent-role-<author|reviewer|autofix|triage|summarizer>
- agent-surface-<cloud|ide|review|ci|server>

Recommended hidden metadata block:

<!-- ai-agent-metadata
metadata_version: 1
work_product_type: change_request
agent: <agent-name>
agent_surface: <cloud|ide|review|ci|server>
agent_role: <author|reviewer|autofix|triage|summarizer>
initiated_by: <human-user-or-unknown>
agent_run: <url-or-id-or-unknown>
source_work_item: <url-or-key-or-unknown>
source_system: <github|gitlab|azure-devops|bitbucket|jira|linear|internal|unknown>
-->

## Commits

For every git commit you create, add commit trailers:

- AI-Agent: <agent-name>
- AI-Agent-Surface: <cloud|ide|review|ci|server>
- AI-Agent-Role: <author|reviewer|autofix|triage|summarizer>
- AI-Agent-Run: <url-or-id-or-unknown>
- AI-Agent-Initiated-By: <human-user-or-unknown>
- AI-Agent-Source-Work-Item: <url-or-key-or-unknown>

If the repository has an approved agent identity, also add:

- Co-authored-by: <approved-agent-identity>

## Work tracker artifacts

For every issue, ticket, work item, task, incident, or equivalent artifact you create or materially modify:

- add system-native labels, tags, custom fields, comments, or properties when permissions allow
- use the same `ai-agent`, `agent-<agent-name>`, `agent-role-*`, and `agent-surface-*` vocabulary where labels or tags are available
- use the required attribution fields above where structured fields or properties are available

## Fallback behavior

Never remove existing agent attribution metadata unless correcting inaccurate metadata.

If you cannot add labels, tags, fields, trailers, or metadata because of permissions or platform limitations, state that in the artifact body or comment under "Agent attribution follow-up".

These instructions are attribution guidance, not a security or compliance boundary. Deterministic enforcement belongs in CI checks, repository hooks, code-host apps, work-tracker automation, policy engines, audit pipelines, or vendor telemetry.

The missing applyTo is intentional: attribution is not file-scoped coding guidance. It should be folded into the global/root context that agents see when acting on repository and work-tracking artifacts.

2. Users install it with existing APM flows

Example install path:

apm install microsoft/apm/packages/agent-attribution
apm install
apm compile --validate
apm compile

This keeps the UX aligned with APM's package-manager mental model. Users should not need a new apm attribution command to understand the feature.

3. APM deploys it through existing target resolution

The attribution package should ride the same target resolution rules as other instructions:

1. explicit --target / --all
2. targets: in apm.yml
3. filesystem auto-detection

Expected generated placement for active targets should follow existing APM target behavior. The package should appear in whichever instruction surfaces APM already manages for the selected harnesses, including root context files and per-harness rule locations.

Examples of expected agent instruction surfaces:

AGENTS.md
CLAUDE.md
GEMINI.md
.github/copilot-instructions.md
.github/instructions/agent-attribution.instructions.md
.claude/rules/agent-attribution.md
.cursor/rules/agent-attribution.mdc

The exact files should follow the current target matrix; the feature should not create a parallel deployment system.

4. Managed AGENTS.md support uses the existing managed section

For AGENTS.md, attribution should be inserted inside the existing APM managed section when users configure:

compilation:
  agents_md:
    mode: managed_section

No new named marker is needed for the MVP.

APM should keep the current safety behavior:

• if the file does not exist, fail clearly rather than guessing
• if markers are missing or duplicated, fail clearly
• preserve content outside the managed section verbatim
• replace only the APM-owned block

This keeps the feature safe for teams that already have hand-written AGENTS.md content while avoiding a second marker protocol.

5. Optional enterprise customization stays in the instruction package

For the MVP, teams can fork or vendor the package to customize labels, agent identities, work-product vocabulary, or metadata fields.

For example:

packages/internal-agent-attribution/
  .apm/instructions/agent-attribution.instructions.md

This avoids introducing a new attribution: manifest schema before there is usage data. If a future schema is needed, it can be designed from real package variants rather than guessed up front.

Reporting convention supplied by the package

The package should recommend a vendor-neutral reporting vocabulary.

Generic labels or tags

ai-agent
agent-<agent-name>
agent-role-<author|reviewer|autofix|triage|summarizer>
agent-surface-<cloud|ide|review|ci|server>

These labels can map to GitHub labels, GitLab labels, Jira labels, Linear labels, Azure DevOps tags, or equivalent system-native tags.

Change-request metadata block

Use this block in pull request, merge request, or equivalent change-request descriptions when the system supports markdown or free-form text:

<!-- ai-agent-metadata
metadata_version: 1
work_product_type: change_request
agent: <agent-name>
agent_surface: <cloud|ide|review|ci|server>
agent_role: <author|reviewer|autofix|triage|summarizer>
initiated_by: <human-user-or-unknown>
agent_run: <url-or-id-or-unknown>
source_work_item: <url-or-key-or-unknown>
source_system: <github|gitlab|azure-devops|bitbucket|jira|linear|internal|unknown>
-->

Commit trailers

AI-Agent: <agent-name>
AI-Agent-Surface: <cloud|ide|review|ci|server>
AI-Agent-Role: <author|reviewer|autofix|triage|summarizer>
AI-Agent-Run: <url-or-id-or-unknown>
AI-Agent-Initiated-By: <human-user-or-unknown>
AI-Agent-Source-Work-Item: <url-or-key-or-unknown>
Co-authored-by: <approved-agent-identity>

Work-tracker fields or properties

Use these names as suggested custom fields, properties, labels, or automation-derived values in Jira, Linear, Azure Boards, GitHub Issues, GitLab Issues, or equivalent systems:

AI Agent Involved: <agent-name>
AI Agent Role: <author|reviewer|autofix|triage|summarizer>
AI Agent Surface: <cloud|ide|review|ci|server>
AI Agent Run: <url-or-id-or-unknown>
AI Agent Source Work Item: <url-or-key-or-unknown>
AI Agent Source System: <system-name-or-unknown>
AI Agent Work Product Type: <change_request|commit|review|issue|ticket|ci_artifact|generated_file|release_note>

The work-tracker fields are advisory. APM should not try to mutate external systems. The instruction package gives agents and downstream automation a shared vocabulary.

Why this should be accepted now

DevX UX fit

This uses the workflow APM users already know:

apm install <package>
apm compile --validate
apm compile

There is no new command family, no new positional-argument order, and no surprising mutation path. Users can preview placement with existing validate flows and commit the generated diff like any other APM-managed context.

The system-specific mapping happens outside the CLI. APM does not ask users whether they are a GitHub/Jira shop, a GitLab/Linear shop, or an internal-platform shop before install succeeds.

Primitives architecture fit

This is an instruction package, not a new primitive. It follows reduced scope and explicit hierarchy:

• source of truth remains under .apm/instructions/
• target-specific output remains generated
• no workflow dispatcher is added
• no target-specific hand-authored copies are introduced
• no long skill or persona bundle is required
• no platform-specific API client is added

The implementation preserves progressive disclosure: a user who needs attribution installs one small package; users who do not need it see no new concepts.

Python architecture fit

The implementation should be O(affected targets), not O(repo size), and should reuse existing compiler/install integration points.

Likely implementation work:

• add the first-party package
• add or update tests proving global instructions from dependencies land in the expected target outputs
• ensure global/no-applyTo instructions are handled consistently in managed-section mode
• add documentation

This does not require a new resolver, registry, policy engine, platform API client, webhook integration, or class hierarchy.

Supply-chain and governance fit

The attribution profile is transparent about its boundary: it instructs agents to self-identify, but does not claim to enforce attribution by itself.

That distinction matters. CI checks, repository hooks, code-host apps, work-tracker automation, policy engines, audit pipelines, and vendor telemetry remain the deterministic enforcement/reporting layer. APM supplies the portable instruction layer and lets enterprise controls verify the resulting artifacts.

Product strategy fit

This reinforces APM's enterprise story: one manifest, portable agent context, reproducible deployment, and governed adoption across heterogeneous agents and heterogeneous development platforms.

A clear CHANGELOG line would be:

feat: add first-party agent attribution package for reportable AI work-product metadata

That is easy to explain, easy to adopt, and hard for single-agent tools to match because the value comes from multi-target projection.

Acceptance criteria

• A first-party attribution package exists in the repo.
• Installing the package adds it to dependencies.apm and deploys the attribution instruction through existing APM install/compile flows.
• The generated instruction appears for active agent targets according to the current target matrix.
• The source instruction describes system-agnostic work-product types: change request, commit, review, issue/ticket/work item, CI artifact, generated file, and release note.
• The source instruction avoids hard dependencies on GitHub, GitLab, Jira, Linear, Azure DevOps, Bitbucket, or any specific external API.
• compilation.agents_md.mode: managed_section inserts the attribution instruction inside the existing APM managed section and preserves content outside the markers.
• apm compile --validate catches malformed generated attribution output like any other generated instruction output.
• Tests cover dependency-sourced global instructions and managed-section output.
• Docs show the one-command install path and examples of labels/tags, change-request metadata, commit trailers, and work-tracker fields.
• Docs explicitly say prompt-level attribution is not enforcement and should be paired with CI, repository hooks, code-host/work-tracker automation, policy engines, audit pipelines, or telemetry when compliance reporting is required.

Non-goals for the MVP

• No new apm attribution command.
• No new top-level attribution: manifest schema.
• No new primitive type.
• No automatic writes to GitHub, GitLab, Jira, Linear, Azure DevOps, Bitbucket, or any external platform.
• No platform-specific API clients, webhooks, or authentication scopes.
• No claim that self-identification instructions are a security or compliance boundary.
• No new named managed-section markers beyond the existing <!-- apm:start --> and <!-- apm:end --> behavior.

Test plan

Add regression tests that create a temporary project with:

1. an apm.yml dependency on the attribution package
2. multiple active targets
3. an existing AGENTS.md with managed-section markers

Then assert:

• install/compile completes successfully
• generated outputs contain # AI agent work-product attribution
• generated outputs contain system-agnostic language such as change request, work item, and work tracker
• generated outputs do not require any specific external system such as GitHub, GitLab, Jira, or Linear
• AGENTS.md preserves content outside the managed markers
• no target receives duplicate attribution blocks
• apm compile --validate passes
• apm audit --ci does not report drift immediately after install/compile

Documentation plan

Add a short enterprise/governance docs section:

• why attribution is useful for reporting
• how to install the package
• what metadata convention the package emits
• how the convention maps to code hosts and work trackers
• how to pair it with CI, repository hooks, platform automation, or telemetry
• what it does not enforce

Suggested docs placement:

docs/src/content/docs/enterprise/agent-attribution.md

Also add one link from the enterprise adoption or governance page.

Why not managed-section-only

Managed-section mode is useful, but it is too low-level as the user-facing answer to attribution.

It solves only one file: AGENTS.md. It does not give teams a reusable attribution convention, does not project equivalent guidance to every harness target, and does not give enterprise users a one-line install story.

The proposed package uses managed-section mode where appropriate, but lets APM own the portable instruction distribution problem end to end.

Why not a new attribution schema yet

A schema may eventually be useful, but starting with one would make the first version harder to accept:

• it would require a new manifest contract before there are real-world variants
• it would force APM to decide every metadata field up front
• it would add migration pressure if the convention changes
• it would invite debates over enforcement semantics that belong outside APM

A first-party package is the smaller, safer primitive. It gives users value immediately and creates real examples for a future schema if demand appears.

Compatibility

This should be non-breaking.

Existing projects see no behavior change unless they install the attribution package. Projects that already use managed-section mode keep the same marker behavior. Projects with hand-authored target files should continue to get the same APM safety behavior around generated file markers and drift checks.

[danielmeppiel]

@yogurtearl what you describe sounds like a custom package with instructions.

I do not think an attribution system should live in the package manager layer, but I agree that a package installed by APM and eventually enforced by APM policy can be leveraged by users to ensure attribution metadata is generated.

That's probably a better case for Hooks though.

[github-actions]

Triage Panel Verdict

Decision: ACCEPT

Issue: [FEATURE] ship a first-party AI agent attribution instruction profile

---

Panel synthesis

DevX UX Expert
Fit: strong. The proposal uses the exact workflow APM users already know (apm install, apm compile). No new command surface, no new manifest schema for the MVP. Attribution deploys through existing target resolution, so users who do not need it see no new concepts. Progressive disclosure is fully preserved. The one-command install story is clean and coherent.

Supply Chain Security Expert
Risk: low. The package consists of a single instruction file with no executable code, no external API clients, no new auth scopes, and no platform-specific write operations. The security boundary is correctly stated: APM delivers the instruction layer; CI hooks, policy engines, and platform automation own deterministic enforcement. That division is the correct architecture for an advisory attribution system.

APM CEO (Strategic Arbiter)
Strategic fit: high. This directly reinforces APM's enterprise governance story -- one manifest, portable agent context, governed adoption. Multi-target projection is APM's differentiator and this feature showcases it clearly. A clean CHANGELOG line: feat: add first-party agent attribution package for reportable AI work-product metadata. Easy to explain, easy to adopt, and hard for single-agent tools to replicate.

Python Architect (conditional)
Implementation scope: bounded. O(affected targets), reuses existing compiler and install integration points. No new resolver, registry, policy engine, class hierarchy, or top-level CLI command needed. Likely work: add the first-party package, ensure global (no applyTo) instructions are handled consistently in managed-section mode, add tests, add docs.

---

Proposed label set

Dimension	Label
Type	type/feature (keep existing)
Theme	theme/governance
Area	area/multi-target, area/package-authoring
Priority	priority/high
Status	status/accepted, status/triaged

Suggested next action

Open an implementation PR adding packages/agent-attribution/ with the instruction package as proposed. The acceptance criteria in the issue body serve as the definition of done. Suggested sequence: add the first-party package, add tests covering global instruction deployment and managed-section output, then add docs under docs/src/content/docs/enterprise/agent-attribution.md. The non-goals list is well-scoped -- hold to it.

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 1.8M · ◷