docopslab-dev 0.1.0

data/docs/agent/skills/git.md

@@ -0,0 +1,170 @@
+# AI Agent Instructions for Git Operations
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+You are an AI agent that helps with git operations.
+
+This document describes protocols for committing and pushing changes to a git DocOps Lab Git repository and interacting with GitHub on behalf of a DocOps Lab contributor.
+
+Table of Contents
+
+- The Basics
+- Repository State
+- Development Procedures
+- Commit Message Conventions
+      - Merging Changes
+- Dev Branch Rules
+- Commit Messages
+- General Style (Conventional Commits)
+      - Commit Description
+      - Commit Types
+      - Commit Body Conventions
+- Use `gh` the GitHub CLI Tool
+
+## The Basics
+
+1. Follow proper branching procedures as outlined in Repository State.
+2. Commit messages should be concise and easy for users to edit.  
+See Commit Messages for guidance.
+3. Always prompt user to approve commits before pushing.
+4. Use `gh` for interacting with GitHub whenever possible.  
+See Use `gh` the GitHub CLI Tool for more information.
+
+## Repository State
+
+Development is done on development _trunk_ branches named like `dev/x.y`, where `x` is the major version and `y` is the minor.
+
+To start development on a new release version:
+
+```
+git checkout main
+git pull origin main
+git checkout -b dev/1.2
+git checkout -b chore/bump-version-1.2.0
+git commit -am "Bumped version attributes in README"
+git checkout dev/1.2
+git merge chore/bump-version-1.2.0
+git push -u origin dev/1.2
+```
+
+## Development Procedures
+
+Work on feature or fix branches off the corresponding `dev/x.y` trunk.
+
+```
+git checkout dev/1.2
+git checkout -b feat/add-widget
+… implement …
+git add .
+git commit -m "feat: add widget"
+git push -u origin feat/add-widget
+gh pr create --base dev/1.2 --title "feat: add widget" --body "Adds a new widget to the dashboard."
+```
+
+**Branch naming conventions** :
+   - `feat/…​` for new features OR improvements
+   - `fix/…​` for bugfixes
+   - `chore/…​` for version bumps and sundry tasks with no product impact
+   - `epic/…​` for large features or changes that span releases
+
+### Commit Message Conventions
+
+**Description (first line) conventions**:
+   - Use present-tense descriptive verbs (“adds widget”, not “added” or “add”)
+   - `feat: …​` for new features OR improvements
+   - `fix: …​` for bugfixes
+   - `chore: …​` for version bumps and sundry tasks with no product impact
+   - `docs: …​` for documentation changes
+   - `test: …​` for test code changes
+   - `refactor: …​` for code restructuring with no functional changes
+   - `style: …​` for formatting, missing semi-colons, etc; no functional changes
+   - `perf: …​` for performance improvements
+   - `auto: …​` for changes to CI/CD pipelines and build system
+
+**Body conventions** :
+   - Use the body to explain what and why vs. how.
+   - Reference issues and pull requests as needed.
+   - Use bullet points (`- text`) and paragraphs as needed for clarity.
+   - Do not hard-wrap lines, but _do_:
+
+      - use 1-sentence per line
+      - keep sentences short
+
+### Merging Changes
+
+Squash-merge branches back into `dev/x.y`:
+
+```
+git checkout dev/1.2
+git checkout -b feat/add-widget
+… implement …
+git add .
+git commit -m "feat: add widget"
+git merge --squash feat/add-widget
+git commit -m "feat: add widget"
+git push origin dev/1.2
+```
+
+Delete merged branches.
+
+## Dev Branch Rules
+
+- Always branch from `dev/x.y`.
+- Always squash-merge into `dev/x.y`.
+- Never merge directly into `main`.
+
+## Commit Messages
+
+This document outlines the protocols for authoring Git commit messages in DocOps Lab projects.
+
+### General Style (Conventional Commits)
+
+DocOps Lab _loosely_ follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for Git commit messages.
+
+Enforcement is not strict, but using Conventional Commits style is encouraged for consistency and clarity.
+
+> **NOTE:** Most DocOps Lab projects do not base Changelog/Release Notes generation on commit messages.
+
+The basic outline for a Conventional Commit message is:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Commit Description
+
+The commit description should be concise and to the point, summarizing the change in 50 characters or less.
+
+Use the _past tense_ rather than imperative mood (e.g., "Added feature X" instead of "Add feature X").
+
+### Commit Types
+
+- Use present-tense descriptive verbs (“adds widget”, not “added” or “add”)
+- `feat: …​` for new features OR improvements
+- `fix: …​` for bugfixes
+- `chore: …​` for version bumps and sundry tasks with no product impact
+- `docs: …​` for documentation changes
+- `test: …​` for test code changes
+- `refactor: …​` for code restructuring with no functional changes
+- `style: …​` for formatting, missing semi-colons, etc; no functional changes
+- `perf: …​` for performance improvements
+- `auto: …​` for changes to CI/CD pipelines and build system
+
+### Commit Body Conventions
+
+- Use the body to explain what and why vs. how.
+- Reference issues and pull requests as needed.
+- Use bullet points (`- text`) and paragraphs as needed for clarity.
+- Do not hard-wrap lines, but _do_:
+
+   - use 1-sentence per line
+   - keep sentences short
+
+## Use `gh` the GitHub CLI Tool
+
+For interacting with GitHub, always prefer using the [GitHub CLI (`gh`)](https://cli.github.com/) tool for issues, PRs, and other GH operations.
+

data/docs/agent/skills/github-issues.md

@@ -0,0 +1,135 @@
+# GitHub Issues Management for AI Agents
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+AI agents assisting in DocOps Lab development tasks should use the Issuer and `gh` CLI tools to manage GitHub issues in project repositories.
+
+Table of Contents
+
+- Managing GitHub Issues with `gh`
+- Bulk-posting Issues with Issuer
+- Issue Types
+- Issue Labels
+- Project-specific Labels
+      - Standard Documentation Labels
+      - Admonition Labels
+      - Other Standard Labels
+
+## Managing GitHub Issues with `gh`
+
+The GitHub CLI tool, `gh`, can be used to manage issues from the command line.
+
+See [GitHub CLI Manual: gh issue](https://cli.github.com/manual/gh_issue) for details on using `gh` to create, view, edit, and manage issues and issue metadata.
+
+Some common commands:
+
+Create a new issue.
+
+```
+gh issue create --title "Issue Title" --body "Issue description." --label "bug,component:docs" --assignee "username"
+```
+
+List open issues.
+
+```
+gh issue list --state open
+```
+
+View a specific issue.
+
+```
+gh issue view <issue-number>
+```
+
+## Bulk-posting Issues with Issuer
+
+The `issuer` tool can be used to bulk-post issues to any repository from a YAML file.
+
+Follow the instructions at [Issuer](https://github.com/DocOps/issuer) to install and use the tool.
+
+## Issue Types
+
+**Task** :
+   A specific piece of work that does not directly lead to a change to the product. Used for research, infrastructure management, and other sundry/chore tasks not necessarily associated with repository code changes.
+
+**Bug** :
+   Reports describing unexpected behavior or malfunctions in the product. Bug issues are used directly and become bugfixes (no technical type change) once resolved.
+
+**Feature** :
+   Requests or ideas for new functionality in the product.
+
+**Improvement** :
+   Enhancements of existing features or capabilities.
+
+**Epic** :
+   An issue or collection of issues with a common goal that may involve work performed across release versions (“milestones”).
+
+## Issue Labels
+
+All DocOps Lab projects use a common convention around GitHub issue labels to categorize and manage issues.
+
+### Project-specific Labels
+
+**`component:<part>`** :
+   Label prefix for arbitrarily named product aspects, modules, interfaces, or subsystems. Common components include `component:docker`, `component:cli`, and `component:docs` (see next section). These correspond to the `part` property in ReleaseHx change records.
+
+### Standard Documentation Labels
+
+**`component:docs`** :
+   Indicates the issue pertains to documentation infrastructure, layout, deployment, but not core content.
+
+**`documentation`** :
+   The issue relates to documentation _content_ updates or improvements.
+
+**`needs:docs`** :
+   The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a `documentation` label.
+
+**`needs:note`** :
+   The issue requires a note in the release history when resolved. Release notes are appended to the description body under `## Release Note`.
+
+**`changelog`** :
+   The issue summary should be included in the changelog for the next release, even if no release note is included.
+
+### Admonition Labels
+
+**`REMOVAL`** :
+   Removes functionality or features.
+
+**`DEPRECATION`** :
+   Announces planned removal of functionality or features in a future release. (Only appropriate for `documentation` issues.)
+
+**`BREAKING`** :
+   Includes one or more changes that are not backward-compatible.
+
+**`SECURITY`** :
+   Addresses or documents a security vulnerability or risk.
+
+### Other Standard Labels
+
+**`question`** :
+   User or community member inquiries about the product or project.
+
+**`priority:high`** :
+   Indicates that the issue is important and should be prioritized for release as soon as possible.
+
+**`priority:low`** :
+   The issue is not urgent and can be addressed in a future release.
+
+**`priority:stretch`** :
+   Issue is slated for the next release but can be bumped if it’s holding up releasee.
+
+**`wontfix`** :
+   The issue will not be addressed. Comment from maintainers should explain why.
+
+**`duplicate`** :
+   The issue is a duplicate of another issue, which should be linked in the comments.
+
+**`posted-by-issuer`** :
+   Indicates that the issue was created by the Issuer tool.
+
+**`good first issue`** :
+   Designates an issue suitable for new contributors to the project.
+
+**`help wanted`** :
+   Indicates that maintainers are seeking assistance from the community to resolve the issue.
+

data/docs/agent/skills/product-release-rollback-and-patching.md

@@ -0,0 +1,71 @@
+# Rolling Back and/or Patching a Product Release
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+As an AI agent, you can assist DocOps Lab developers in executing product-release patching and rolling back.
+
+Table of Contents
+
+- Rollback Failsafe
+- Standard Patching
+
+## Rollback Failsafe
+
+If a release must be rolled back and retracted, you must revert the changes and “yank” the artifacts.
+
+```
+git tag -d v<$tok.majmin>.<$tok.patch>
+git push origin :refs/tags/v<$tok.majmin>.<$tok.patch>
+git revert -m 1 <merge-commit>
+git push origin main
+```
+
+Retract or yank the artifacts (DockerHub, RubyGems, etc) and nullify the GH release.
+
+```
+gh release delete v<$tok.majmin>.<$tok.patch>
+gem yank --version <$tok.majmin>.<$tok.patch> <gemname>
+docker rmi <image>:<$tok.majmin>.<$tok.patch>
+```
+
+Be sure to un-publish any additional artifacts specific to the project.
+
+## Standard Patching
+
+Perform patch work against the earliest affected `release/x.y`. These examples use `1.1`, `1.2`, and `1.2.1` as example versions.
+
+Patch development procedure
+
+```
+git checkout release/1.1
+git checkout -b fix/parser-typo
+# … FIX …
+git add .
+git commit -m "fix: correct parser typo"
+git push origin fix/parser-typo
+# … TEST …
+git checkout release/1.1
+git merge --squash fix/parser-typo
+git commit -m "fix: correct parser typo"
+git push origin release/1.1
+git tag -a v1.2 -m "Patch release 1.2"
+git push origin v1.2
+```
+
+Example forward porting procedure
+
+```
+git checkout release/1.2
+git cherry-pick <commit-hash>
+# … TEST …
+git push origin release/1.2
+git tag -a v1.2.1 -m "Patch release 1.2.1"
+git push origin v1.2.1
+```
+
+> **NOTE:** Be sure to change `1.1`, `1.2`, and `1.2.1` to the actual affected branches and versions.
+
+Repeat for every affected branch then release the patched versions.
+
+> **NOTE:** Between minor versions, patch versions may vary due to inconsistent applicability of patches.
+

data/docs/agent/skills/rake-cli-dev.md

@@ -0,0 +1,57 @@
+# Agent Rake CLI Guide
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+If you need to add or modify Rake tasks for the current project, follow the guidelines in this document.
+
+Table of Contents
+
+- Rake CLIs
+- Rake CLI Model
+
+## Rake CLIs
+
+We use Rake for internal repo tasks and chores, including build operations, test-suite execution, unconventional testing, code linting and cleanup, etc.
+
+Users of our released products should never be asked to use `rake` commands during the normal course of daily operations, if ever.
+
+Rake is less versatile than Thor, but it is simpler for executing straightforward methods and series of methods. It likewise requires (and permits) considerably less application-specific creativity and customization.
+
+Innovative UIs are not justified for internal tooling. Our developer-facing utilities are fairly robust, but the UI for executing them need not be.
+
+At DocOps Lab, we save inventive interfaces for domain-optimized operations.
+
+### Rake CLI Model
+
+```
+rake domain:action:target[option1,option2]
+```
+
+Where both `domain`` and `target` are optional, as of course are arguments that go in the braces.
+
+Think of the domain as a component “scope” within the codebase or project.
+
+Domains either indicate a distinct module or component within the codebase or general tasks using upstream dependencies.
+
+No domain means local, project-specific tasks.
+
+Example 3-part task with an optional argument
+
+```
+rake labdev:lint:docs[README.adoc]
+```
+
+In the above case, the domain is from the `docopslab-dev` library/gem.
+
+Example 3-part task with a local domain reference
+
+```
+rake gemdo:build
+```
+
+The above command has a local domain `gemdo` for referencing commands that affect a gem that happens to be embedded in a larger repo. A code repo containing more than one gem might use:
+
+```
+rake gemdo:build:gemname
+```
+

data/docs/agent/skills/readme-driven-dev.md

@@ -0,0 +1,13 @@
+# README-driven Development
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+DocOps Lab practices software development that revolves around `README.adoc` and uses other AsciiDoc and YAML files to radically single source all product and documentation code.
+
+We will eventually provide detailed documentation of the conventions and protocols involved in this method.
+
+For now, Agents should:
+
+- Peruse the local `README.adoc` and `specs/data/*.{yml,yaml}`
+- Prompt their Operators to provide examples from relevant/neighboring projects.
+

data/docs/agent/skills/release-history.md

@@ -0,0 +1,29 @@
+# Preparing a Version Release History Document
+
+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) -->
+- [Product Change Tracking and Documentation](/docs/product-change-docs/)
+
+ReleaseHx automatically generates release notes and changelogs from GitHub Issues and PRs when properly labeled.
+
+> **NOTE:** Every DocOps Lab project implements ReleaseHx differently as a way of “eating our own dog food”.
+
+Refer to any given project’s documentation for specific instructions on how to prepare changes for inclusion in release notes and changelogs.
+
+The general procedure is as follows:
+
+1. Generate a draft release history in YAML.
+
+```
+bundle exec rhx <version> --yaml --fetch
+```
+2. Edit the generated YAML to ensure clarity and completeness.
+3. Generate the Markdown version.
+
+```
+bundle exec rhx <version> --md docs/release/<version>.md
+```
+

data/docs/agent/skills/ruby.md

@@ -0,0 +1,192 @@
+# Ruby Coding Guide for DocOps Lab AI Agents
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+## Conventions
+
+DocOps Lab largely follows Ruby’s community conventions, with some exceptions. Conventions are either reiterated or clarified here.
+
+However, conventions are not exhaustively listed, and deviations are rarely pointed out as such.
+
+### Naming Conventions
+
+- Use `snake_case` for variable and method names.
+- Use `CamelCase` for class and module names.
+- Use `SCREAMING_SNAKE_CASE` for constants.
+- Use descriptive names that convey the purpose of the variable, method, or class.
+- Avoid abbreviations unless they are widely understood.
+- Use verbs for method names to indicate actions.
+- Use nouns for class and module names to indicate entities.
+
+### Architectural Conventions
+
+- Use classes and class instance methods for objects that work like _objects_ — they have state and do not act on other objects' state.
+- Use module methods acting on objects or carrying out general operations/utility functions.
+- Use Rake for internal (developer) CLI; use Thor for user-facing CLI
+- Gems may begin life as a module within another gem.
+
+### Path Conventions
+
+- Use `lib/` for main application code.
+
+   - `lib/<project_name>.rb` for the main file
+   - `lib/<project_name>/` for supporting files and modules
+   - `lib/<project_name>/<module_name>/` for submodules
+- Use `spec/` for specifications and tests.
+- Use `docs/` or `_docs/` for documentation.
+- Use `build/` for pre-runtime artifacts.
+- Use `_build/` as default in applications that generate files at runtime, unless another path is more appropriate (ex: `_site/` in Jekyll-centric apps).
+- Do NOT assume or insist upon perfect alignment with Ruby path conventions:
+
+   - `SomeModule` or `SomeClass` may be sourced at `lib/some_module.rb` or `lib/some_class.rb` instead of `lib/some/module.rb` or `lib/some/class.rb`.
+   - Some modules like `SchemaGraphy` and `AsciiDoc` are never broken up into `schema_graphy` or `ascii_doc` namespaces.
+   - Modules with multiple parallel sibling modules in a category like (`WriteOps`, `DraftOps`) belong in paths like `lib/ops/write.rb` instead of `lib/write_ops.rb` or `lib/write/ops.rb`.
+
+### Syntax Conventions
+
+- Use 2 spaces for indentation.
+- Limit lines to 120 characters or so when possible.
+- Use parentheses for method calls with arguments, but omit them for methods without arguments.
+- Do not use parentheses in method definitions (`def method_name arg1, arg2`).
+- Use single quotes for strings that do not require interpolation or special symbols.
+- Use double quotes for strings that require interpolation or special symbols.
+
+### Commenting Conventions
+
+See [DocOps Lab Code Commenting Guidance](/docs/code-commenting/) for detailed commenting conventions.
+
+## RuboCop Config
+
+```
+# RuboCop configuration for DocOps Lab projects
+# This is the baseline configuration distributed via docopslab-dev
+
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  
+Style/MethodDefParentheses:
+  EnforcedStyle: require_no_parentheses
+
+Style/MethodCallWithArgsParentheses:
+  EnforcedStyle: require_parentheses
+  AllowParenthesesInMultilineCall: true
+  AllowParenthesesInChaining: true
+
+# Allow longer lines for documentation
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns:
+    - '\A\s*#.*\z' # Comments
+    - '\A\s*\*.*\z' # Rdoc comments
+
+Metrics/MethodLength:
+  Max: 25
+
+# Allow longer blocks for Rake tasks and RSpec
+Metrics/BlockLength:
+  AllowedMethods:
+    - describe
+    - context
+    - feature
+    - scenario
+    - let
+    - let!
+    - subject
+    - task
+    - namespace
+  Max: 50
+
+# Documentation not required for internal tooling
+Style/Documentation:
+  Enabled: false
+
+# Allow TODO comments
+Style/CommentAnnotation:
+  Keywords:
+    - TODO
+    - FIXME
+    - OPTIMIZE
+    - HACK
+    - REVIEW
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Layout/FirstParameterIndentation:
+  EnforcedStyle: consistent
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/MultilineMethodCallBraceLayout:
+  EnforcedStyle: same_line
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: aligned
+
+Layout/FirstMethodArgumentLineBreak:
+  Enabled: true
+
+Layout/TrailingWhitespace:
+  Enabled: true
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: true
+
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/SpaceAroundOperators:
+  Enabled: false
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: false
+  EnforcedStyle: no_space
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: true
+
+Lint/UselessAssignment:
+  Enabled: true
+
+Lint/IneffectiveAccessModifier:
+  Enabled: true
+
+Security/YAMLLoad:
+  Enabled: false # Projects may intentionally use unsafe YAML loading
+
+Security/Eval:
+  Enabled: true # Catch and replace with safer alternatives
+
+# Disable Naming/PredicateMethod - we use generate_, run_, sync_, etc for actions
+Naming/PredicateMethod:
+  Enabled: false
+```
+

data/docs/agent/skills/schemagraphy-sgyml.md

@@ -0,0 +1,18 @@
+# SchemaGraphy/SGYML 101
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+SGYML stands for SchemaGraphy YAML-based Modeling Language, a format designed, standardized, and maintained by DocOps Lab.
+
+It is a specialized YAML preprocessing syntax that provides:
+
+- A human-readable schema model that can define, govern, and parse the structure and contents of complex data objects and text documents alike
+- An extension for YAML documents to incorporate new properties like `$ref` transclusion directives and inheritance/overlay properties
+- A standardization around a base subset of YAML capabilities to constrain the complexity of YAML documents and support thereof
+- Highly semantic data-typing to replace YAML’s clunky model
+
+SchemaGraphy Schemas and the SGYML and tooling to support them are in a nascent stage, still under development.
+
+Check [SchemaGraphy](/projects/schemagraphy/) for the latest information on SchemaGraphy and SGYML.
+
+> **TIP:** If the codebase you are working on uses SGYML or SchemaGraphy Schemas, check for a path `../schemagraphy/` (relative to the project root).