docopslab-dev 0.2.0 → 0.3.0

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

@@ -1,174 +0,0 @@
-# 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
-
-<dl>
-<dt class="hdlist1">Task</dt>
-<dd>
-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.
-</dd>
-<dt class="hdlist1">Bug</dt>
-<dd>
-Reports describing unexpected behavior or malfunctions in the product. Bug issues are used directly and become bugfixes (no technical type change) once resolved.
-</dd>
-<dt class="hdlist1">Feature</dt>
-<dd>
-Requests or ideas for new functionality in the product.
-</dd>
-<dt class="hdlist1">Improvement</dt>
-<dd>
-Enhancements of existing features or capabilities.
-</dd>
-<dt class="hdlist1">Epic</dt>
-<dd>
-An issue or collection of issues with a common goal that may involve work performed across release versions (“milestones”).
-</dd>
-</dl>
-
-## Issue Labels
-
-All DocOps Lab projects use a common convention around GitHub issue labels to categorize and manage issues.
-
-### Project-specific Labels
-
-<dl>
-<dt class="hdlist1">`component:<part>`</dt>
-<dd>
-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.
-</dd>
-</dl>
-
-### Standard Documentation Labels
-
-<dl>
-<dt class="hdlist1">`component:docs`</dt>
-<dd>
-Indicates the issue pertains to documentation infrastructure, layout, deployment, but not core content.
-</dd>
-<dt class="hdlist1">`documentation`</dt>
-<dd>
-The issue relates to documentation _content_ updates or improvements.
-</dd>
-<dt class="hdlist1">`needs:docs`</dt>
-<dd>
-The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a `documentation` label.
-</dd>
-<dt class="hdlist1">`needs:note`</dt>
-<dd>
-The issue requires a note in the release history when resolved. Release notes are appended to the description body under `## Release Note`.
-</dd>
-<dt class="hdlist1">`changelog`</dt>
-<dd>
-The issue summary should be included in the changelog for the next release, even if no release note is included.
-</dd>
-</dl>
-
-### Admonition Labels
-
-<dl>
-<dt class="hdlist1">`REMOVAL`</dt>
-<dd>
-Removes functionality or features.
-</dd>
-<dt class="hdlist1">`DEPRECATION`</dt>
-<dd>
-Announces planned removal of functionality or features in a future release. (Only appropriate for `documentation` issues.)
-</dd>
-<dt class="hdlist1">`BREAKING`</dt>
-<dd>
-Includes one or more changes that are not backward-compatible.
-</dd>
-<dt class="hdlist1">`SECURITY`</dt>
-<dd>
-Addresses or documents a security vulnerability or risk.
-</dd>
-</dl>
-
-### Other Standard Labels
-
-<dl>
-<dt class="hdlist1">`question`</dt>
-<dd>
-User or community member inquiries about the product or project.
-</dd>
-<dt class="hdlist1">`priority:high`</dt>
-<dd>
-Indicates that the issue is important and should be prioritized for release as soon as possible.
-</dd>
-<dt class="hdlist1">`priority:low`</dt>
-<dd>
-The issue is not urgent and can be addressed in a future release.
-</dd>
-<dt class="hdlist1">`priority:stretch`</dt>
-<dd>
-Issue is slated for the next release but can be bumped if it’s holding up releasee.
-</dd>
-<dt class="hdlist1">`wontfix`</dt>
-<dd>
-The issue will not be addressed. Comment from maintainers should explain why.
-</dd>
-<dt class="hdlist1">`duplicate`</dt>
-<dd>
-The issue is a duplicate of another issue, which should be linked in the comments.
-</dd>
-<dt class="hdlist1">`posted-by-issuer`</dt>
-<dd>
-Indicates that the issue was created by the Issuer tool.
-</dd>
-<dt class="hdlist1">`good first issue`</dt>
-<dd>
-Designates an issue suitable for new contributors to the project.
-</dd>
-<dt class="hdlist1">`help wanted`</dt>
-<dd>
-Indicates that maintainers are seeking assistance from the community to resolve the issue.
-</dd>
-</dl>
-

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

@@ -1,71 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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.
-
-2. Edit the generated YAML to ensure clarity and completeness.
-
-3. Generate the Markdown version.
-

data/docs/agent/skills/ruby.md

@@ -1,203 +0,0 @@
-# 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.
-
-- 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:
-
-### 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

@@ -1,21 +0,0 @@
-# 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).

data/docs/agent/skills/tests-running.md

@@ -1,33 +0,0 @@
-# Running Tests in DocOps Lab Projects
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-As an AI agent, you can help DocOps Lab developers run tests effectively using standard Rake tasks.
-
-All Ruby gem projects with tests should implement these standard Rake tasks in their `Rakefile`:
-
-<dl>
-<dt class="hdlist1">`bundle exec rake rspec`</dt>
-<dd>
-Run RSpec test suite using the standard pattern matcher.
-</dd>
-<dt class="hdlist1">`bundle exec rake cli_test`</dt>
-<dd>
-Validate command-line interface functionality. May test basic CLI loading, help output, version information.
-</dd>
-<dt class="hdlist1">`bundle exec rake yaml_test`</dt>
-<dd>
-Validate YAML configuration files and data structures. Should test all project YAML files for syntax correctness.
-</dd>
-<dt class="hdlist1">`bundle exec rake pr_test`</dt>
-<dd>
-Comprehensive test suite for pre-commit and pull request validation. Typically includes: RSpec tests, CLI tests, YAML validation.
-</dd>
-<dt class="hdlist1">`bundle exec rake install_local`</dt>
-<dd>
-Build and install the project locally for testing.
-</dd>
-</dl>
-
-Note that non-gem projects may have some or all of these tasks, as applicable.
-

data/docs/agent/skills/tests-writing.md

@@ -1,68 +0,0 @@
-# Writing Tests for DocOps Lab Projects
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-As an AI agent, you can help DocOps Lab developers write comprehensive tests following established patterns and categories.
-
-Tests should be organized into these categories:
-
-<dl>
-<dt class="hdlist1">Unit Tests</dt>
-<dd>
-- Module loading and initialization
-
-- Class structure validation
-
-- Basic functionality verification
-
-- Individual method testing
-</dd>
-<dt class="hdlist1">Integration Tests</dt>
-<dd>
-- Data processing workflows
-
-- Template rendering operations
-
-- Configuration loading scenarios
-
-- API client functionality (where applicable)
-</dd>
-<dt class="hdlist1">Validation Tests</dt>
-<dd>
-- File format compliance (YAML, JSON)
-
-- Configuration schema validation
-
-- Template syntax verification
-
-- Command-line option parsing
-</dd>
-</dl>
-
-All Ruby gem projects with tests should implement these standard Rake tasks in their `Rakefile`:
-
-<dl>
-<dt class="hdlist1">`bundle exec rake rspec`</dt>
-<dd>
-Run RSpec test suite using the standard pattern matcher.
-</dd>
-<dt class="hdlist1">`bundle exec rake cli_test`</dt>
-<dd>
-Validate command-line interface functionality. May test basic CLI loading, help output, version information.
-</dd>
-<dt class="hdlist1">`bundle exec rake yaml_test`</dt>
-<dd>
-Validate YAML configuration files and data structures. Should test all project YAML files for syntax correctness.
-</dd>
-<dt class="hdlist1">`bundle exec rake pr_test`</dt>
-<dd>
-Comprehensive test suite for pre-commit and pull request validation. Typically includes: RSpec tests, CLI tests, YAML validation.
-</dd>
-<dt class="hdlist1">`bundle exec rake install_local`</dt>
-<dd>
-Build and install the project locally for testing.
-</dd>
-</dl>
-
-Note that non-gem projects may have some or all of these tasks, as applicable.
-