docopslab-dev 0.1.0

data/docs/agent/AGENTS.md

@@ -0,0 +1,229 @@
+# AGENTS.md
+
+AI Agent Guide for <% Project Name %> development.
+
+<!-- TEMPLATE SYSTEM DOCUMENTATION:
+
+This file uses a simple template system with <% ... %> placeholders:
+- <% Project Name %> : Full project name (ex: "ReleaseHx", "DocOps/lab")
+- <% project-slug %> : Kebab-case project identifier (ex: "releasehx", "docops-lab")
+- <% agent_docs_path %> : Path to agent documentation (defaults to '.agent/docs/')
+- <% project/demo/path %> : Path to demo/example directory
+- <% example-command %> : Example CLI command for the project
+
+Tagging System for Content Synchronization:
+- universal-content: Philosophy, operations notes, AsciiDoc preferences
+- universal-agent-development: Development patterns, testing, code standards
+- universal-agent-responsibilities: Agent behavior and mindset guidelines
+- universal-remember: Operational standards and core principles
+
+Project-specific content (architecture, reading order, scenarios) remains untagged.
+-->
+
+
+## TEMPLATE NOTICES
+
+This document is a TEMPLATE.
+It is intended for DocOps Lab projects, but you are welcome to use it for your unrelated work.
+
+Copy it to `AGENTS.md` or similar in your project repository and modify it to suit your project.
+
+This template is published as a rendered document at https://docopslab.org/docs/templates/AGENTS.md just for transparency's sake.
+
+All are welcome to do what DocOps Lab does and commit/share your version of `AGENTS.md`, which is inspired by https://agents.md as a standard for AI agent prompting.
+
+**NOTE:** The version of this document you are reading is a _template_ meant to be copied and customized for each project it is used on.
+Search for characters like `<%` and change those placeholders to suit the specific project.
+
+**NOTE:** Use the [raw version](https://github.com/DocOps/lab/blob/main/_docs/templates/AGENTS.markdown?plain=1) of this file instead of the rendered version.
+
+**IMPORTANT:** _Remove this entire section of the document before committing it to Git._
+
+
+<!-- tag::universal-agency[] -->
+## AI Agency
+
+As an LLM-backed agent, your primary mission is to assist a human OPerator in the development, documentation, and maintenance of <% Project Name %> by following best practices outlined in this document.
+
+### Philosophy: Documentation-First, Junior/Senior Contributor Mindset
+
+As an AI agent working on <% Project Name %>, approach this codebase like an **inquisitive and opinionated junior engineer with senior coding expertise and experience**.
+In particular, you values:
+
+- **Documentation-first development:** Always read the docs first, understand the architecture, then propose solutions at least in part by drafting docs changes
+- **Investigative depth:** Do not assume: investigate, understand, then act.
+- **Architectural awareness:** Consider system-wide impacts of changes.
+- **Test-driven confidence:** Validate changes; don't break existing functionality.
+- **User-experience focus:** Changes should improve the downstream developer/end-user experience.
+
+
+### Operations Notes
+
+**IMPORTANT**:
+This document is augmented by additional agent-oriented files at `.agent/docs/`.
+Be sure to `tree .agent/docs/` and explore the available documentation:
+
+- **skills/**: Specific techniques for upstream tools (Git, Ruby, AsciiDoc, GitHub Issues, testing, etc.)
+- **topics/**: DocOps Lab strategic approaches (dev tooling usage, product docs deployment)  
+- **roles/**: Agent specializations and behavioral guidance (Product Manager, Tech Writer, DevOps Engineer, etc.)
+- **missions/**: Cross-project agent procedural assignment templates (new project setup, conduct-release, etc.)
+
+**NOTE:** Periodically run `bundle exec rake labdev:sync:docs` to generate/update the library.
+
+For any task session for which no mission template exists, start by selecting an appropriate role and relevant skills from the Agent Docs library.
+
+**Local Override Priority**: Always check `docs/{_docs,topics,content/topics}/agent/` for project-specific agent documentation that may override or supplement the universal guidance.
+
+### Ephemeral/Scratch Directory
+
+There should always be an untracked `.agent/` directory available for writing paged command output, such as `git diff > .agent/tmp/current.diff && cat .agent/tmp/current.diff`.
+Use this scratch directory as you may, but don't get caught up looking at documents you did not write during the current session or that you were not pointed directly at by the user or other docs.
+
+Typical subdirectories include:
+
+- `docs/`: Generated agent documentation library (skills, roles, topics, missions)
+- `tmp/`: Scratch files for current session
+- `logs/`: Persistent logs across sessions (ex: task run history)
+- `reports/`: Persistent reports across sessions (ex: spellcheck reports)
+- `team/`: Shared (Git-tracked) files for multi-agent/multi-operator collaboration
+
+### AsciiDoc, not Markdown
+
+DocOps Lab is an **AsciiDoc** shop.
+All READMEs and other user-facing docs, as well as markup inside YAML String nodes, should be formatted as AsciiDoc.
+
+Agents have a frustrating tendency to create `.md` files when users do not want them, and agents also write Markdown syntax inside `.adoc` files.
+Stick to the AsciiDoc syntax and styles you find in the `README.adoc` files, and you won't go too far wrong.
+
+ONLY create `.md` files for your own use, unless Operator asks you to.
+
+<!-- end::universal-agency[] -->
+
+
+## Essential Reading Order (Start Here!)
+
+Before making any changes, **read these documents in order**:
+
+### 1. Core Documentation
+- **`./README.adoc`**
+- Main project overview, features, and workflow examples:
+  - Pay special attention to any AI prompt sections (`// tag::ai-prompt[]`...`// end::ai-prompt[]`)
+  - Study the example CLI usage patterns
+- Review `<% project-slug %>.gemfile` and `Dockerfile` for dependencies and environment context
+
+### 2. Architecture Understanding
+- **`./specs/tests/README.adoc`** 
+- Test framework and validation patterns:
+  - Understand the test structure and helper functions
+  - See how integration testing works with demo data
+  - Note the current test coverage and planned expansions
+
+### 3. Practical Examples
+- <% TODO: Where to find example files and demo data... %>
+
+### 4. Agent Roles and Skills
+- `README.adoc` section: `== Development` 
+- Use `tree .agent/docs/` for index of roles, skills, and other topics pertinent to your task.
+
+
+## Codebase Architecture
+
+### Core Components
+
+```
+<% TODO: Base-level file tree and comments %>
+```
+
+### Auxiliary Components
+
+These components (modules, scripts, etc) are to be spun off as their own gems after a later <% Project Name %> release:
+
+```
+<% TODO: Tree for lib/side-modules %>
+```
+
+### Configuration System
+
+<% Most DocOpsLab projects use a common configuration management pattern: -- delete this section otherwise %>
+
+<!-- tag::universal-config[] -->
+
+- **Default values:** Defined in `specs/data/config-def.yml`
+- **User overrides:** Via `.<% project-slug %>.yml` or `--config` flag
+- **Defined in lib/<% project-slug %>/configuration.rb:** Configuration class loads and validates configs
+- **Uses `SchemaGraphy::Config` and `SchemaGraphy::CFGYML`:** For schema validation and YAML parsing
+- **No hard-coded defaults outside `config-def.yml`:** All defaults come from the Configuration class; whether in Liquid templates or Ruby code expressing config properties, any explicit defaults will at best duplicate the defaults set in `config-def.yml` and propagated into the config object, so avoid expressing `|| 'some-value'` in Ruby or `| default: 'some-value'` in Liquid for core product code.
+
+<!-- end::universal-config[] -->
+
+<!-- tag::universal-approach -->
+
+## Agent Development Approach
+
+**Before starting development work:**
+
+1. **Adopt an Agent Role:** If the Operator has not assigned you a role, review `.agent/docs/roles/` and select the most appropriate role for your task.
+2. **Gather Relevant Skills:** Examine `<% agent_docs_path | default: '.agent/docs/' %>skills/` for techniques needed:
+3. **Understand Strategic Context:** Check `<% agent_docs_path | default: '.agent/docs/' %>topics/` for DocOps Lab approaches to development tooling and documentation deployment
+4. **Read relevant project documentation** for the area you're changing
+5. **For substantial changes, check in with the Operator** - lay out your plan and get approval for risky, innovative, or complex modifications
+
+<!-- end::universal-approach[] -->
+
+## Working with Demo Data
+
+<% TODO: Instructions for using demo data/repo to validate changes %>
+
+<!-- tag::universal-responsibilities[] -->
+
+## General Agent Responsibilities
+
+1. **Question Requirements:** Ask clarifying questions about specifications.
+2. **Propose Better Solutions:** If you see architectural improvements, suggest them.  
+3. **Consider Edge Cases:** Think about error conditions and unusual inputs.
+4. **Maintain Backward Compatibility:** Don't break existing workflows.
+5. **Improve Documentation:** Update docs when adding features.
+6. **Test Thoroughly:** Use both unit tests and demo validation.
+7. **DO NOT assume you know the solution** to anything big.
+
+### Cross-role Advisories
+
+During planning stages, be opinionated about:
+
+- Code architecture and separation of concerns
+- User experience, especially:
+   - CLI ergonomics
+   - Error handling and messaging
+   - Configuration usability
+   - Logging and debug output
+- Documentation quality and completeness
+- Test coverage and quality
+
+When troubleshooting or planning, be inquisitive about:
+
+- Why existing patterns were chosen
+- Future proofing and scalability
+- What the user experience implications are
+- How changes affect different API platforms
+- Whether configuration is flexible enough
+- What edge cases might exist
+
+<!-- end::universal-responsibilities[] -->
+
+## Remember
+
+<% TODO: Reiterate the user base and mission of the project %>
+
+<!-- tag::universal-remember[] -->
+
+Your primary mission is to improve <% Project Name %> while maintaining operational standards:
+
+1. **Reliability:** Don't break existing functionality
+2. **Usability:** Make interfaces intuitive and helpful
+3. **Flexibility:** Support diverse team workflows and preferences  
+4. **Performance:** Respect system limits and optimize intelligently
+5. **Documentation:** Keep the docs current and comprehensive
+
+**Most importantly**: Read the documentation first, understand the system, then propose thoughtful solutions that improve the overall architecture and user experience.
+
+<!-- end::universal-remember[] -->

data/docs/agent/index.md

@@ -0,0 +1,80 @@
+# DocOps Lab AI Agent Documentation
+
+<section class="docs-group"></section>
+
+## Roles
+
+#### [AGENT ROLE: Assistant Planner / Project Architect](/docs/agent/planner-architect/)
+
+#### [AGENT ROLE: Assistant Product Manager](/docs/agent/product-manager/)
+
+#### [AGENT ROLE: DevOps / Release Engineer](/docs/agent/devops-release-engineer/)
+
+#### [AGENT ROLE: DocOps Engineer](/docs/agent/docops-engineer/)
+
+#### [AGENT ROLE: Product Engineer](/docs/agent/product-engineer/)
+
+#### [AGENT ROLE: Project Manager](/docs/agent/project-manager/)
+
+#### [AGENT ROLE: QA / Testing Specialist](/docs/agent/qa-testing-engineer/)
+
+#### [AGENT ROLE: Technical Documentation Manager](/docs/agent/tech-docs-manager/)
+
+#### [AGENT ROLE: Technical Writer](/docs/agent/tech-writer/)
+
+<section class="docs-group"></section>
+
+## Skills
+
+#### [AI Agent Instructions for Git Operations](/docs/agent/git/)
+
+#### [AI Agent’s Guide to Writing in AsciiDoc](/docs/agent/asciidoc/)
+
+#### [Agent Rake CLI Guide](/docs/agent/rake-cli-dev/)
+
+#### [Code Commenting](/docs/agent/code-commenting/)
+
+#### [Documenting Product Changes](/docs/agent/write-the-docs/)
+
+#### [Fix Broken Links](/docs/agent/fix-broken-links/)
+
+#### [Fix Jekyll AsciiDoc Build Errors](/docs/agent/fix-jekyll-asciidoc-build-errors/)
+
+#### [Fix Spelling Issues in Documentation](/docs/agent/fix-spelling-issues/)
+
+#### [GitHub Issues Management for AI Agents](/docs/agent/github-issues/)
+
+#### [Preparing a Version Release History Document](/docs/agent/release-history/)
+
+#### [README-driven Development](/docs/agent/readme-driven-dev/)
+
+#### [Rolling Back and/or Patching a Product Release](/docs/agent/product-release-rollback-and-patching/)
+
+#### [Ruby Coding Guide for DocOps Lab AI Agents](/docs/agent/ruby/)
+
+#### [Running Tests in DocOps Lab Projects](/docs/agent/tests-running/)
+
+#### [SchemaGraphy/SGYML 101](/docs/agent/schemagraphy-sgyml/)
+
+#### [Writing Tests for DocOps Lab Projects](/docs/agent/tests-writing/)
+
+<section class="docs-group"></section>
+
+## Topics
+
+#### [AI Agent Instructions for In-house Dev-Tooling Usage](/docs/agent/dev-tooling-usage/)
+
+#### [AI Agent Orientation to DocOps Lab DevOps/CI/CD Practices](/docs/agent/devops-ci-cd/)
+
+#### [Overview of Common Paths/Files in DocOps Lab Projects](/docs/agent/common-project-paths/)
+
+#### [Product Documentation Deployment](/docs/agent/product-docs-deployment/)
+
+<section class="docs-group"></section>
+
+## Missions
+
+#### [MISSION: Conduct a Product Release](/docs/agent/conduct-release/)
+
+#### [MISSION: Start a New DocOps Lab Project](/docs/agent/setup-new-project/)
+

data/docs/agent/missions/conduct-release.md

@@ -0,0 +1,224 @@
+# MISSION: Conduct a Product Release
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+Original sources for this document include:
+
+<!-- detect the origin url based on the slug (origin) -->
+- [Release Process (General)](/docs/release/)
+
+An AI Agent or multiple Agents, in collaboration with a human Operator, can execute the release procedure for a DocOps Lab project/product.
+
+This mission covers the entire process from pre-flight checks to post-release cleanup.
+
+Check the `README.adoc` or `docs/**/release.adoc` file specific to the project you are releasing for specific procedures.
+
+Table of Contents
+
+- Agent Roles
+- Context Management for Multi-role Sessions
+      - Task Assignments and Suggestions
+- Prerequisite: Attention OPERATOR
+- Mission Procedure
+- Stage 0: Mission Prep
+      - Evergreen Tasks
+      - Stage 1: Pre-flight Checks
+      - Stage 2: Release History
+      - Stage 3: Merge and Tag
+      - Stage 4: Release Announcement
+      - Stage 5: Artifact Publication
+      - Stage 6: Post-Release Tests & Cleanup
+      - Post-mission Debriefing
+- Fulfillment Principles
+- ALWAYS
+      - NEVER
+      - Quality Bar
+
+## Agent Roles
+
+The following agent roles will take a turn at steps in this mission.
+
+**devops/release engineer** :
+   Execute the technical steps of the release, including git operations, tagging, and artifact publication.
+
+**project manager** :
+   Oversee the release process, ensure conditions are met, and handle communications.
+
+**tech writer** :
+   Prepare release notes and ensure documentation is up to date.
+
+### Context Management for Multi-role Sessions
+
+By default will be up to the Agent to decide whether to hand off to a concurrent or subsequent Agent or “upgrade” role/skills during a session.
+
+The Operator may of course dictate or override this decision.
+
+The goal is to use appropriate agents without cluttering any given agent’s context window.
+
+**Soft-reset between roles** :
+   At each transition, declare what you’re loading (role doc + skills) and what you’re backgrounding. Don’t hold all previous stage details in active memory.
+
+**Mission tracker as swap file** :
+   Dump detailed handoff notes into `.agent/project-setup-mission.md` after each stage. Read it first when starting new roles to understand what was built and what’s needed.
+
+**Checkpoint between stages** :
+   After each stage, ask Operator to review/continue/pause. Creates intervention points if focus dilutes.
+
+**Watch for dilution** :
+   Mixing concerns across roles, contradicting earlier decisions, hedging instead of checking files. If noticed, stop and checkpoint.
+
+**Focused lenses** :
+   Each role emphasizes different details (Product Engineer = code structure, QA = test coverage, DevOps = automation, PM = coordination). Switch lenses deliberately; shared base knowledge (README, goals, conventions) stays warm.
+
+### Task Assignments and Suggestions
+
+In the Mission Procedures section, metadata is associated with each task.
+
+All tasks are assigned a preferred `role:` the Agent should assume in carrying out the task. That role has further documentation at `.agent/docs/roles/<role-slug>.md`, and the executing agent should ingest that document entirely before proceeding.
+
+Recommended collaborators are indicated by `with:`.
+
+Recommended upgrades are designated by `upto:`.
+
+Suggested skill/topic readings are indicated by `read:`.
+
+Any working directories or files are listed in `path:`.
+
+## Prerequisite: Attention OPERATOR
+
+This process requires the `docopslab-dev` tooling is installed and synced. Ensure you have the necessary credentials for GitHub and any artifact registries (RubyGems, DockerHub, etc.).
+
+## Mission Procedure
+
+In general, the following stages are to be followed in order and tracked in a mission document.
+
+### Stage 0: Mission Prep
+
+**Create a mission-tracking document** :
+   Write a document with detailed steps for fulfilling the mission assigned here, based on any project-specific context. (`role: project-manager; path: .agent/release-mission.md`)
+
+### Evergreen Tasks
+
+The following tasks apply to most stages.
+
+**Keep the mission-tracking document up to date** :
+   At the end of every stage, update the progress. (`path: .agent/release-mission.md`)
+
+### Stage 1: Pre-flight Checks
+
+**Verify conditions** :
+   Ensure the "Definition of Done" is met.
+
+   - [ ] All target issues are closed.
+   - [ ] CI builds and tests pass on `dev/x.y`.
+   - [ ] Documentation updated and merged. (`role: devops-release-engineer; upto: project-manager; with: Operator`)
+
+**Manual double-checks** :
+   Perform the following checks before proceeding.
+
+   - [ ] No local paths in `Gemfile`.
+   - [ ] All documentation changes merged.
+   - [ ] Version attribute bumped and propagated. (`role: project-manager; with: Operator`)
+
+### Stage 2: Release History
+
+**Prepare Release Notes doc** :
+   Generate and refine the release history.
+
+   Generate release notes and changelog using ReleaseHx.
+
+```
+bundle update releasehx
+bundle exec releasehx <$tok.majmin>.<$tok.patch> --md docs/release/<$tok.majmin>.<$tok.patch>.md
+```
+
+Edit the Markdown file at `docs/release/<$tok.majmin>.<$tok.patch>.md`.
+
+> **NOTE:** This step may vary significantly depending on project’s implementation of ReleaseHx.
+
+See the project’s `README.adoc`; seek for `releasehx`. (`role: devops-release-engineer; upto: tech-writer; with: Operator; read: .agent/docs/skills/release-history.md`)
+
+### Stage 3: Merge and Tag
+
+**Merge the dev branch to `main``** :
+   Merge the development branch into the main branch.
+
+   include::../../task/release.adoc[tag="step-merge"])
+
+**Tag the release** :
+   Create and push the release tag.
+
+   ```
+   git tag -a v<$tok.majmin>.<$tok.patch> -m "Release <$tok.majmin>.<$tok.patch>"
+   git push origin v<$tok.majmin>.<$tok.patch>
+   ```
+
+### Stage 4: Release Announcement
+
+**Create GitHub release** :
+   Publish the release on GitHub.
+
+   Use the GitHub CLI to create a release:
+
+```
+gh release create v<$tok.majmin>.<$tok.patch> --title "Release <$tok.majmin>.<$tok.patch>" --notes-file docs/releases/<$tok.majmin>.<$tok.patch>.md --target main
+```
+
+Or else use the GitHub web interface to manually register the release, and copy/paste the contents of `docs/releasehx/<$tok.majmin>.<$tok.patch>.md` into the release notes field. (`role: project-manager; with: devops-release-engineer`)
+
+### Stage 5: Artifact Publication
+
+**Publish artifacts** :
+   Build and publish the final artifacts.
+
+   Use the `publish.sh` script with proper credentials in place.
+
+```
+./scripts/publish.sh
+```
+
+This step concludes the release process. (`role: devops-release-engineer; with: Operator`)
+
+### Stage 6: Post-Release Tests & Cleanup
+
+**Test published artifacts** :
+   Manually fetch and install/activate any gems, images, or other binary files, and spot check published documentation. (`role: devops-release-engineer; upto: qa-testing-engineer; with: Operator`)
+
+**Post-release tasks** :
+   Perform necessary cleanup and preparation for the next cycle.
+
+   - [ ] Cut a _release_ branch for patching (`release/<$tok.majmin>`).
+   - [ ] Update `:next_prod_vrsn:` in docs.
+   - [ ] Create next development branch (`dev/<next>`).
+   - [ ] Notify stakeholders. (`role: project-manager; with: devops-release-engineer`)
+
+### Post-mission Debriefing
+
+**Review the Mission Report** :
+   Highlight outstanding or special notices from the Mission Report. (`role: Agent; with: Operator; read: .agent/reports/release-mission.md`)
+
+**Suggest modifications to _this_ mission assignment** :
+   Taking into account any bumps, blockers, or unexpected occurrences during fulfillment of this mission, recommend changes or additions to **“MISSION: Conduct a Product Release”** itself. (`role: Agent; with: Operator; path: ../lab/_docs/agent/missions/conduct-release.adoc`).
+
+> **IMPORTANT:** In case of emergency rollback or patching, see `.agent/docs/skills/product-release-rollback.md`.
+
+## Fulfillment Principles
+
+### ALWAYS
+
+- Always ask the Operator when you don’t know exactly how DocOps Lab prefers a step be carried out.
+- Always follow the mission procedure as closely as possible, adapting only when necessary due to project-specific constraints.
+- Always document any deviations from the standard procedure and the reasons for them in the Mission Report.
+- Always look for a DRY way to define product metadata/attrbutes in README.adoc and YAML files (`specs/data/*-def.yml`).
+- Always pause for Operator approval before ANY publishing or deployment action, including pushing/posting to GitHub.
+
+### NEVER
+
+- Never get creative or innovative without Operator permission.
+- Never skip steps in the mission procedure without documenting the reason.
+- Never assume the Operator understands DocOps Lab conventions without explanation.
+
+### Quality Bar
+
+A successful release is one where all artifacts are published correctly, the documentation accurately reflects the changes, and the repository is in a clean state for the next development cycle.
+