agentdefaults/examples/devops-documentation-task.yaml at main · Quazmoz/agentdefaults · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
task_id: devops-docs-gitops-001
goal: >-
  Reconcile and update the current-state documentation for the Jenkins and
  Ansible GitOps flows, including evidence-backed Mermaid diagrams and
  explicit ownership, trigger, promotion, rollback, and reconciliation paths.
mode: implement
domain: gitops_docs
state_intent: current_state
audience:
  - platform_engineers
  - operators

target:
  kind: documentation_repository
  identifier: org/platform-documentation
  branch_or_version: main
  paths:
    - docs/gitops/jenkins.md
    - docs/gitops/ansible.md
    - docs/architecture/

sources:
  repositories:
    - org/jenkins-gitops
    - org/ansible-gitops
    - org/terraform-platform
  systems:
    - Jenkins controller configuration
    - Automation Platform controller configuration
    - Azure platform dependencies
  required_sources:
    - Jenkins seed, JCasC, shared-library, and pipeline configuration relevant to the documented flow
    - Ansible projects, playbooks, roles, inventories, job templates, and workflow configuration relevant to the documented flow
    - Terraform and Azure configuration needed to establish platform dependencies and state ownership

diagram_policy:
  required: true
  formats:
    - mermaid
    - existing_opaque_image
  asset_roots:
    - docs/images/

context:
  suspected_drift:
    - Existing documentation may describe historical Jenkins jobs that are no longer generated by GitOps.
    - Existing image diagrams may not have editable source files.
  repository_conventions:
    - Documentation is Markdown.
    - Mermaid diagrams are embedded in Markdown.
    - Existing image diagrams are referenced from repository asset folders.

authority:
  maximum_permission_class: mutate_reversible
  authorized_mutations:
    - Update Markdown, Mermaid source, navigation references, and documentation-owned assets in the documentation repository.
  approval_required: false

constraints:
  non_goals:
    - Do not modify Jenkins, Automation Platform, Terraform, Azure, CI/CD, credentials, or production runtime state.
    - Do not redesign the GitOps architecture while documenting it.
  preserve_conventions: true
  security_privacy:
    - Do not publish secret values, tokens, private keys, or credential material.
    - Avoid unnecessary tenant, subscription, host, or endpoint identifiers in broad-audience documentation.

acceptance:
  - Jenkins and Ansible GitOps documentation matches the inspected current implementation.
  - Each GitOps flow identifies desired-state source, review gate, trigger, validation, controller, execution target, authoritative state, success/failure signals, reconciliation, promotion, and rollback.
  - Mermaid diagrams contain only evidence-backed nodes and edges.
  - Opaque image diagrams without editable source are preserved and explicitly reported if they cannot be safely updated.
  - No infrastructure or runtime system is changed.

verification:
  required_checks:
    - Run the documentation repository validator or site build when available.
    - Validate Markdown links and image references when tooling exists.
    - Validate Mermaid syntax/rendering when repository tooling exists.
    - Review the final diff for unrelated changes and secret leakage.
  source_reconciliation:
    - Reconcile documented Jenkins flow against active seed, JCasC, Jenkinsfile, and shared-library paths.
    - Reconcile documented Ansible flow against active project, playbook, inventory, job-template, and workflow paths.
    - Reconcile platform dependencies against relevant Terraform and Azure evidence.
  postconditions:
    - Updated documents are present at the authorized paths.
    - Current-state claims are traceable to inspected source evidence.
    - No known material documentation drift remains in the requested scope.