docopslab-dev 0.2.0 → 0.3.0

data/docs/agent/skills/write-the-docs.md

@@ -1,116 +0,0 @@
-# Documenting Product Changes
-
-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/)
-
-Each contributor of product code or docs changes is responsible for preparing that change to be included in release documentation, _when applicable_.
-
-Table of Contents
-
-- GitHub Issues Labels
-- Change Documentation
-  - User-Facing Documentation
-  - Internal Documentation
-- Release Note Entry
-
-## GitHub Issues Labels
-
-GitHub Issues are use specific labels to indicate documentation expectations.
-
-<dl>
-<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>
-
-Issues labeled `changelog` will automatically appear in the Changelog section of the Release History document. Release notes must be manually entered.
-
-## Change Documentation
-
-When a change to the product affects user-facing functionality, the documentation needs to change.
-
-For early product versions, most documentation appears in the root `README.adoc` file. When a product has a `docs/content/` path, documentation changes usually have a home in an AsciiDoc (`.adoc`) file in a subdirectory.
-
-Reference matter should be documented where it is defined, such as in `specs/data/*.yml` files.
-
-When a product matures (prior to 1.0), the documentation should move into new paths, separated depending on whether it is user-facing or internal.
-
-In either case, the way to discover where to put documentation changes is to use a `docopslab-dev` _skim_ task on the existing docs source. These skims are semantic outlines of the source files in their converted state. They can be used for navigation, content discovery, and change impact analysis.
-
-### User-Facing Documentation
-
-End-user docs, including API documentation, is usually sourced in `docs/content/`, alongside asset files for the documentation site (images, CSS, etc.).
-
-The `docs/` path is typically a Jekyll site’s source path, but in most cases a pre-build operation will generate supplemental files in `docs/built/` or the like.
-
-If the changes you are documenting are user-facing, use the tasks below to determine where the relevant documentation lives.
-
-<dl>
-<dt class="hdlist1">Skim the docs</dt>
-</dl>
-
-```
-bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json
-bundle exec rake labdev:skim:adoc[docs/,tree,json] > .agent/docs/skim-docs.json
-```
-
-### Internal Documentation
-
-Generally speaking, internal documentation (for developers, maintainers, and their AI agents), belongs in `_docs/` and `.agent/docs/` paths.
-
-The `_docs/agent/` path is for overlays that take priority over parallel docs in `.agent/docs/` (maintained by docopslab-dev library syncing).
-
-<dl>
-<dt class="hdlist1">Skim the README</dt>
-</dl>
-
-```
-bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json
-```
-
-<dl>
-<dt class="hdlist1">Skim the internal docs</dt>
-</dl>
-
-```
-bundle exec rake labdev:skim:adoc[_docs/,tree,json] > .agent/docs/skim-internal.json
-```
-
-<dl>
-<dt class="hdlist1">Skim the agent docs to see if any overlay is needed</dt>
-</dl>
-
-```
-bundle exec rake labdev:skim:md[.agent/docs/:_docs/agent/,tree,json] > .agent/docs/skim-agent.json
-```
-
-If a local instruction contradicts or differs arbitrarily from the main DocOps Lab developer/contributor docs, create an overlay file in `_docs/agent/*` with the same sub-path and filename.
-
-## Release Note Entry
-
-User-facing product changes that deserve explanation (not just notice) require a release note.
-
-Add a release note for a given issue by appending it to the issue body following a `## Release Note` heading.
-
-Example
-
-```markdown
-## Release Note
-
-The content of the release note goes here, in Markdown format.
-Try to keep it to one paragraph with minimal formatting.
-```
-

data/docs/agent/topics/common-project-paths.md

@@ -1,169 +0,0 @@
-# Overview of Common Paths/Files in DocOps Lab Projects
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-_If you are creating a new DocOPs Lab project_, use this guide to establish initial files. This also applies to adding major facilities or features to an existing project.
-
-_If you are just getting to know a DocOps Lab codebase_, favor the project’s `README.adoc` file over this guide.
-
-DocOps Lab projects tend to contain many of the same files across codebases. Documentation of these files in particular will be added when possible, but for now this basic guide will have to suffice.
-
-Table of Contents
-
-- Documentation Paths
-- Configuration
-- Containerization
-- Ruby Files
-- Automation Paths
-- Quality Assurance Paths
-- Generative AI Paths
-
-## Documentation Paths
-
-Only two files are required in _every_ DocOps Lab project, though most projects should contain most of these files, depending on the nature of the codebase. A `docs/` or `_docs/` directory is close to the third universal requirement, necessary by the time a project reaches version 1.0.0.
-
-<dl>
-<dt class="hdlist1">`README.adoc`</dt>
-<dd>
-Project documentation in AsciiDoc format, providing an overview and instructions. DocOps Lab READMEs typically include single-sourcing data for the product as AsciiDoc attributes. See the [AsciiSourcerer project](https://github.com/DocOps/asciisourcerer).
-</dd>
-<dt class="hdlist1">`LICENSE`</dt>
-<dd>
-The project’s license file, specifying the terms under which the code can be used and distributed. Almost always **MIT License**.
-</dd>
-<dt class="hdlist1">`docs/` / `_docs/`</dt>
-<dd>
-Directory for additional documentation, guides, and related materials. Typically `docs/` for product _user_ documentation, whereas `_docs/` is for (a) repos that are mainly for websites or (b) _internal engineering_ documentation files (more often found at `docs/_docs/`). Both might be present in the case of a website that hosts docs and _has its own_ docs.
-
-A `docs/` directory will typically have its own `Gemfile`, configs, and assets for Jekyll, Yard, and other generators. A `_docs/` directory is usually a content-only subordinate to the main project and its content, and may not have separate configs or assets.
-</dd>
-</dl>
-
-## Configuration
-
-<dl>
-<dt class="hdlist1">`.config/`</dt>
-<dd>
-Configuration files for tooling used in development, building, or QA/testing. Not always used.
-
-<dl>
-<dt class="hdlist1">`.config/releasehx.yml`</dt>
-<dd>
-Configuration file for ReleaseHx, a tool for generating release notes and changelogs.
-</dd>
-<dt class="hdlist1">`.config/jekyll.yml`</dt>
-<dd>
-Configuration file for Jekyll docs publication. For Jekyll extensions (themes and plugins), this file is typically `./_config.yml` to conform to Jekyll defaults.
-</dd>
-<dt class="hdlist1">`.config/vale.ini`</dt>
-<dd>
-Configuration file for Vale, a linter for prose, defining linting rules and styles.
-</dd>
-</dl>
-</dd>
-<dt class="hdlist1">`.config/.vendor/`</dt>
-<dd>
-Directory for upstream configuration files, mostly or entirely managed by `docopsab-dev` gem. These files are not tracked in Git but are synced with upstream sources and maintained by DocOps Lab.
-</dd>
-</dl>
-
-## Containerization
-
-<dl>
-<dt class="hdlist1">`Dockerfile`</dt>
-<dd>
-Dockerfile for building the project’s Docker image, defining the environment and dependencies.
-</dd>
-<dt class="hdlist1">`.dockerignore`</dt>
-<dd>
-Specifies files and directories to ignore when building the Docker image.
-</dd>
-<dt class="hdlist1">`docker-compose.yml`</dt>
-<dd>
-Defines and runs multi-container Docker applications, _if applicable_.
-</dd>
-</dl>
-
-## Ruby Files
-
-These files are common to Ruby-based DocOps Lab projects. The `Gemfile` and `Gemfile.lock` may be present in non-Ruby codebases that use Ruby development dependencies, such as ReleaseHx.
-
-<dl>
-<dt class="hdlist1">`Gemfile`</dt>
-<dd>
-Ruby Bundler file, specifying gem dependencies for the project.
-</dd>
-<dt class="hdlist1">`Gemfile.lock`</dt>
-<dd>
-Generated by Bundler, this file locks the gem versions used in the project.
-</dd>
-<dt class="hdlist1">`.ruby-version`</dt>
-<dd>
-Specifies the Ruby version used in the project.
-</dd>
-<dt class="hdlist1">`<gemname>.gemspec`</dt>
-<dd>
-Ruby gem specification file, defining the gem’s metadata and dependencies.
-</dd>
-</dl>
-
-## Automation Paths
-
-<dl>
-<dt class="hdlist1">`Rakefile`</dt>
-<dd>
-Ruby Rakefile for defining tasks and automation scripts.
-</dd>
-<dt class="hdlist1">`scripts/`</dt>
-<dd>
-Custom scripts for automating tasks related to development, testing, and deployment.
-</dd>
-<dt class="hdlist1">`.github/workflows/`</dt>
-<dd>
-GitHub Actions workflows for CI/CD, defining automated build, test, and deployment processes.
-</dd>
-</dl>
-
-## Quality Assurance Paths
-
-Any files containing _requirements_, _specifications_, _definitions_, _schemas_, or _tests_ should be stored in the `specs/` directory, as detailed in [DocOps Lab Testing & Specifications](/docs/testing/).
-
-<dl>
-<dt class="hdlist1">`specs/`</dt>
-<dd>
-General directory for content that specifies, defines, or tests elements of the product. See [DocOps Lab Testing & Specifications](/docs/testing/).
-
-<dl>
-<dt class="hdlist1">`specs/data/`</dt>
-<dd>
-Definition and schema files.
-</dd>
-<dt class="hdlist1">`specs/tests/rspec/`</dt>
-<dd>
-RSpec tests for Ruby codebases.
-</dd>
-<dt class="hdlist1">`../<product-slug>-demo/`</dt>
-<dd>
-Major products typically have a sibling repo that serves as a proving grounds and/or for demonstrative purposes.
-</dd>
-</dl>
-</dd>
-</dl>
-
-## Generative AI Paths
-
-<dl>
-<dt class="hdlist1">`.github/copilot-instructions.md`</dt>
-<dd>
-Instructions for GitHub Copilot, providing guidance on how any cloud-based GH Copilot assistance should be oriented toward a given codebase.
-</dd>
-<dt class="hdlist1">`AGENTS.md`</dt>
-<dd>
-General for _local_ coding agents. May duplicate `.github/copilot-instructions.md` or provide additional context.
-</dd>
-<dt class="hdlist1">`.agent/`</dt>
-<dd>
-A directory for temporary/scratch files used by local coding agents.
-</dd>
-</dl>
-

data/docs/agent/topics/dev-tooling-usage.md

@@ -1,195 +0,0 @@
-# AI Agent Instructions for In-house Dev-Tooling Usage
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-This guide pertains to the `docopslab-dev` environment. For complete documentation, see the [project’s README](/projects/docops-box/).
-
-> **IMPORTANT:** The environment described and provided here is _not_ optimized for DocOps Lab _applications_ used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see [DocOps Box](/projects/docops-box) for a full-featured docs-focused workspace, runtime, and production environment.
-
-This gem mainly supplies rake tasks for performing common development operations across and between projects.
-
-Table of Contents
-
-- Standard Usage
-- Override Commands
-- Task Reference
-  - Typical Workflow
-  - Override Commands
-- Customization
-  - Local Overrides
-
-## Standard Usage
-
-With a proper native Ruby environment, use the `bundle exec` prefix to ensure consistent dependency versioning.
-
-Sync all configs and assets
-
-```
-bundle exec rake labdev:sync:all
-```
-
-Run all linters
-
-```
-bundle exec rake labdev:lint:all
-```
-
-Auto-fix safe issues
-
-```
-bundle exec rake labdev:heal:all
-```
-
-## Override Commands
-
-Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.
-
-<dl>
-<dt class="hdlist1">RuboCop</dt>
-<dd>
-```
-bundle exec rubocop --config .config/rubocop.yml [options]
-bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
-bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
-```
-</dd>
-<dt class="hdlist1">Vale</dt>
-<dd>
-```
-vale --config=.config/vale.ini [options] [files]
-vale --config=.config/vale.ini README.adoc
-vale --config=.config/vale.ini --minAlertLevel=error .
-```
-</dd>
-<dt class="hdlist1">HTMLProofer</dt>
-<dd>
-```
-bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
-```
-</dd>
-</dl>
-
-## Task Reference
-
-```
-bundle exec rake --tasks | grep labdev:
-```
-
-> **TIP:** To hide the `labdev:` tasks from the standard `rake --tasks` output for an integrated project, use:
->
->
->
->
->
-> ```
-> bundle exec rake --tasks | grep -v labdev:
-> ```
-
-### Typical Workflow
-
-This tool is for working on DocOps Lab projects or possibly unrelated projects that wish to follow our methodology. A typical workflow might look as follows.
-
-Normal development
-
-```
-git add .
-git commit -m "Add new feature"
-```
-
-+ This should yield warnings and errors if active linters find issues.
-
-1. Auto-fix what you can.
-
-2. Review the changes.
-
-3. Commit the fixes.
-
-4. Handle any remaining manual fixes.
-
-5. Fix remaining issues manually.
-
-6. Try pushing.
-
-> **TIP:** Bypass the pre-push gates (usually to test or demo the failure at origin):
->
->
->
->
->
-> ```
-> git push --no-verify
-> ```
-
-### Override Commands
-
-Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.
-
-<dl>
-<dt class="hdlist1">RuboCop</dt>
-<dd>
-```
-bundle exec rubocop --config .config/rubocop.yml [options]
-bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
-bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
-```
-</dd>
-<dt class="hdlist1">Vale</dt>
-<dd>
-```
-vale --config=.config/vale.ini [options] [files]
-vale --config=.config/vale.ini README.adoc
-vale --config=.config/vale.ini --minAlertLevel=error .
-```
-</dd>
-<dt class="hdlist1">HTMLProofer</dt>
-<dd>
-```
-bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
-```
-</dd>
-</dl>
-
-## Customization
-
-Override settings by editing the project configs:
-
-- `.config/docopslab-dev.yml`
-
-- `.config/rubocop.yml`
-
-- `.config/vale.ini`
-
-- `.config/htmlproofer.yml`
-
-- `.config/actionlint.yml`
-
-- `.config/shellcheckrc`
-
-Your configurations will inherit from the base configurations and source libraries as sourced in the Git-ignored `.config/.vendor/docopslab/` path.
-
-### Local Overrides
-
-Projects using `docopslab-dev` will have a configuration structure like the following:
-
-```tree
-.config/
-├── docopslab-dev.yml # Project manifest (tracked)
-├── actionlint.yml # Project config (tracked; inherits from base)
-├── htmlproofer.local.yml # Project config (tracked; inherits from base)
-├── htmlproofer.yml # Generated config (untracked)
-├── rubocop.yml # Project config (tracked; inherits from base)
-├── shellcheckrc # ShellCheck config (tracked)
-├── vale.ini # Generated active config (untracked)
-├── vale.local.ini # Project config (tracked; inherits from base)
-├── .vendor/ # Base configs (untracked; synced)
-│ └── docopslab/
-│ ├── htmlproofer.yml # Centrally managed base
-│ ├── rubocop.yml # Centrally managed base
-│ └── vale.ini # Centrally managed base
-scripts/ # Project override scripts
-    └── .vendor/ # Centrally managed scripts
-.github/workflows/ # CI/CD workflows (tracked)
-env.docopslab # Environment variables (git tracked)
-env.private # Environment variables (git ignored)
-```
-

data/docs/agent/topics/devops-ci-cd.md

@@ -1,57 +0,0 @@
-# AI Agent Orientation to DocOps Lab DevOps/CI/CD Practices
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-DocOps Lab is in a very nascent stage of establishing shared (cross-repo) tools, workflows, and protocols to for automating development, integration, build, and deployment processes.
-
-DocOps Lab uses GitHub Actions and Docker as primary platforms for integration and deployment automation.
-
-For now you can get a good idea for getting started with automation by checking the standard paths in the current project (`Dockerfile`, `docker-compose.yml`, `.github/workflos/`, `Rakefile`, `scripts/`) as well as looking at similar DocOps Lab projects that have more established CI/CD workflows.
-
-The rest of this document is snippets from various relevant internal documentation.
-
-Table of Contents
-
-- Common Automation Scripts
-- Docker Usage
-  - Application Dockerfiles and Images
-- See Also
-
-## Common Automation Scripts
-
-Some DocOps Lab projects include highly customized automation scripts, but most contain or employ some common scripts that are primarily stored in this repository and/or deployed as Docker images for universal access during development, testing, and deployment.
-
-These procedures can always be invoked by way of local scripts located in `scripts/`. These include:
-
-- `build.sh`
-
-- `publish.sh`
-
-Common scripts are managed through the lnk:/docs/lab-dev-setup/[`docopslab-dev` gem].
-
-Ruby projects will generally include a `Rakefile` (in the base directory), which automates various Ruby tasks.
-
-## Docker Usage
-
-DocOps Lab projects make extensive use of Docker.
-
-All runtime projects provide have their own Docker image hosted on Docker Hub and sourced in their own repo’s `Dockerfile`. This way a reliable executable is available across all platforms and environments.
-
-Some of our CI/CD pipelines will be “Dockerized” to provide consistent builds and tests across numerous repos.
-
-The DocOps Box project maintains an elaborate Dockerfile and image/container management script (`docksh`) that can help manage multiple environments. This is most advantageous for non-Ruby/non-programmer users building a complex documentation codebase in the Ruby/DocOps Lab ecosystem or using multiple DocOps Lab or similar tools across numerous multiple codebases.
-
-### Application Dockerfiles and Images
-
-Each runtime application project has its own `Dockerfile` in the root of its repository.
-
-This Dockerfile defines the image that will be built and pushed to Docker Hub for use by anyone needing to run the application.
-
-> **NOTE:** Some Dockerfiles combine multiple applications, such as the [issuer-rhx image](https://github.com/DocOps), which combines both the Issuer and ReleaseHx applications.
-
-## See Also
-
-- `./dev-tooling-usage.md`
-
-- `../skills/git.md`
-

data/docs/agent/topics/product-docs-deployment.md

@@ -1,31 +0,0 @@
-# Product Documentation Deployment
-
-This document is intended for AI agents operating within a DocOps Lab environment.
-
-Most DocOps Lab projects have their own documentation sites, also built with Jekyll and AsciiDoc, often including YARD for Ruby API reference generation.
-
-For less-formalized projects, documentation is restricted to `README.adoc` and other `*.adoc` files. These are hosted as GitHub Pages sites from their respective repositories, but using a consistent URL structure centered on the `docopslab.org` domain hosted here.
-
-The URL structure is as follows:
-
-<dl>
-<dt class="hdlist1">Project landing page</dt>
-<dd>
-`https://<project>.docopslab.org/`
-
-At a minimum, this should be a subset of the `README.adoc` file.
-</dd>
-<dt class="hdlist1">Product user docs</dt>
-<dd>
-`https://<project>.docopslab.org/docs/`
-</dd>
-<dt class="hdlist1">Product developer docs</dt>
-<dd>
-`https://<project>.docopslab.org/docs/api/(<apiname>/)`
-
-The final `<apiname>` directory is only applicable when the product contains multiple distinct APIs.
-</dd>
-</dl>
-
-GH Pages configuration for these sites enables deployment by way of a clean `gh-pages` branch containing only generated documentation artifacts and the `CNAME` file.
-

data/docs/library-readme.adoc

@@ -1,39 +0,0 @@
-= DocOps Lab: Agent Library
-:doctype: article
-
-This is the *{empty}DocOps Lab agent library* distribution branch.
-It is not intended for direct use as a cloned project.
-
-It is published and consumed automatically by the `docopslab-dev` gem's `labdev:sync:library` Rake task.
-
-
-[[contents]]
-== Contents
-
-`config-packs/`::
-Bundled configuration files for linters and quality tools (Vale, RuboCop, actionlint, etc.), organized by tool name.
-
-`docs/agent/`::
-Generated agent-guidance documents covering roles, skills, missions, and topics for AI agents working on DocOps Lab projects.
-
-`hooks/`::
-Git hook scripts installed by `labdev:init:hooks`.
-
-`scripts/`::
-Utility scripts available to projects via `labdev:sync:scripts`.
-
-`templates/`::
-Boilerplate and sync-cast template files, including `AGENTS.markdown` (the canonical template for project-level `AGENTS.md` files).
-
-`catalog.json`::
-Machine-generated catalog of all files in this library snapshot, including SHA256 checksums and the timestamp of the generating commit.
-
-
-[[usage]]
-== Usage
-
-Projects using `docopslab-dev` fetch this library with:
-
- bundle exec rake labdev:sync:library
-
-For full documentation, see the https://github.com/DocOps/lab/tree/main/gems/docopslab-dev[docopslab-dev README].