Aiwg auto-provenance

Generate W3C PROV-compliant provenance records automatically when agents create or modify artifacts

install

source · Clone the upstream repo

git clone https://github.com/jmagly/aiwg

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/auto-provenance" ~/.claude/skills/jmagly-aiwg-auto-provenance && rm -rf "$T"

manifest: .agents/skills/auto-provenance/SKILL.md

source content

Auto-Provenance

Automatically generates W3C PROV-compliant provenance records when agents create or modify artifacts.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

"W3C PROV" → provenance standard reference
"lineage" → data/artifact lineage tracking
"provenance for [artifact]" → specific artifact provenance

Purpose

Ensures every artifact created by AIWG agents has a provenance record, maintaining an auditable chain of derivation from requirements through implementation. Implements the W3C PROV-DM Entity-Activity-Agent model automatically, without requiring agents to manually create records.

Activation Conditions

This skill activates when:

New artifact creation - Agent writes a new file to
```
.aiwg/
```
or
```
src/
```
directories
Artifact modification - Agent modifies an existing tracked artifact
Content with @-mentions - Written content contains derivation @-mentions
Manual trigger - User explicitly requests provenance tracking

Skip Conditions

File is in
```
.aiwg/working/
```
(temporary files)
File is in
```
.aiwg/ralph/
```
(loop state, not artifacts)
File is in
```
.aiwg/research/provenance/records/
```
(provenance about provenance would be circular)
File is
```
node_modules/
```
,
```
.git/
```
, or build output
File is a provenance record itself (
```
.prov.yaml
```
)

Behavior

When a tracked artifact is created or modified:

Detect artifact event
- Monitor file writes in tracked directories
- Classify as generation (new) or modification (existing)
- Extract agent identity from context
Extract derivation sources
- Parse @-mentions in the written content
- Classify relationship types:
  - ```
  @implements
```
  -> derivation_type: implements
- ```
@tests
```
    -> derivation_type: tests
  - ```
  @extends
```
  -> derivation_type: extends
- ```
@depends
```
    -> derivation_type: depends
  - Generic
```
@path
```
    -> derivation_type: derives_from
Generate provenance record
- Create Entity with URN ID and content hash
- Create Activity with type, timestamps
- Create Agent with name, type, tool version
- Create Relationships (wasGeneratedBy, wasAssociatedWith, wasDerivedFrom)

Validate and save

Validate against

@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml

Save to

.aiwg/research/provenance/records/<artifact-name>.prov.yaml

Update provenance index

Report
- Brief confirmation: "Provenance record created for <artifact>"
- Warning if derivation sources could not be resolved

Agent Orchestration

Primary: Provenance Manager (handles record creation and validation)
Passive participants: All artifact-generating agents (Software Implementer, Test Engineer, Requirements Analyst, Architecture Designer, Technical Writer, Documentation Synthesizer, Security Auditor, API Designer)

Integration

With Mention Wiring

@-mentions serve as the primary source of derivation relationships:

integration:
  mention_wiring:
    source: "@-mentions in artifact content"
    target: "wasDerivedFrom relationships in provenance record"
    mapping:
      "@implements": "implements"
      "@tests": "tests"
      "@extends": "extends"
      "@depends": "depends"
      "@source": "derives_from"

With Qualified References

Qualified @-mentions provide relationship type information:

integration:
  qualified_references:
    source: "qualified @-mentions (@implements @path)"
    target: "typed derivation relationships"

With HITL Gates

Phase transitions trigger provenance completeness checks:

integration:
  hitl_gates:
    action: validate_provenance_coverage
    trigger: phase_transition

Configuration

skill:
  name: auto-provenance
  type: passive
  always_active_for:
    - provenance-manager
    - software-implementer
    - test-engineer
    - requirements-analyst
    - architecture-designer
    - technical-writer
    - documentation-synthesizer
    - security-auditor
    - api-designer
  file_triggers:
    - pattern: ".aiwg/**/*.md"
    - pattern: ".aiwg/**/*.yaml"
    - pattern: "src/**/*.ts"
    - pattern: "src/**/*.js"
    - pattern: "test/**/*.ts"
    - pattern: "test/**/*.js"
  exclude:
    - pattern: ".aiwg/working/**"
    - pattern: ".aiwg/ralph/**"
    - pattern: ".aiwg/research/provenance/records/**"
    - pattern: "**/*.prov.yaml"
  auto_create: true
  auto_update: true
  validate_on_create: true

Output Locations

Provenance records:

.aiwg/research/provenance/records/<name>.prov.yaml

Provenance index:
```
.aiwg/research/provenance/index.yaml
```
Validation reports:
```
.aiwg/reports/provenance-report.md
```

References

@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/provenance-manager.md - Provenance Manager agent
@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml - PROV record schema
@.aiwg/research/provenance/docs/provenance-guide.md - Provenance guide
@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/provenance-tracking.md - Provenance tracking rules
@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/mention-wiring.md - @-mention wiring patterns
@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/qualified-references.md - Qualified reference rules