Dev-tooling Usage

Using docopslab-dev tooling with DocOps Lab project codebases

This guide pertains to the docopslab-dev environment. For complete documentation, see the project’s README.

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 for a full-featured docs-focused workspace, runtime, and production environment.

For full setup instructions, see DocOps Lab Dev-tooling Setup.

For configuration details, see DocOps Lab Dev-tooling Configuration.

This gem mainly supplies rake tasks for performing common development operations across and between projects.

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

Docker Usage

The container runs with a base command of /bin/bash in interactive mode. Any command you pass it will assume you are starting at a normal prompt, with the exception of rake, which will always convert to bundle exec rake.

Other Ruby commands will either need an explicit lab-dev bundle exec or may run without Bundler, like asciidoctor (globally installed for Vale availability) and bundle itself. Non-Ruby commands like vale and shellcheck are immediately available.

First time in a DocOps Lab project

lab-dev :sync:all

Regular development workflow

lab-dev :sync:all
lab-dev :lint:all
lab-dev :heal

Irregular commands

lab-dev vale --config .config/vale.ini README.adoc
lab-dev bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
lab-dev asciidoctor -o tmp/docs.html README.adoc

Interactive shell for debugging

lab-dev

The Docker container persists gems on the host machine in the local .bundle/ path for performance. All tools use the host project’s Gemfile for version consistency.

Make sure container-managed paths are not tracked in Git. Add .config/.vendor/, scripts/.vendor, and .bundle/ to .gitignore.

Advanced library caching with Docker

Mount your system cache directory to the container for persistent caching of library assets across sessions and projects.

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -v ~/.cache/docopslab:/home/docops/.cache/docopslab \
  docopslab/dev

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.

RuboCop

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

Vale

vale --config=.config/vale.ini [options] [files]
vale --config=.config/vale.ini README.adoc
vale --config=.config/vale.ini --minAlertLevel=error .

HTMLProofer

bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site

See [more-example-commands] for additional common commands.

Handy Tasks

Lint only for AsciiDoc syntax issues

bundle exec rake labdev:lint:adoc

Lint only for prose/text issues

bundle exec rake labdev:lint:text

Lint for both text and markup issues

bundle exec rake labdev:lint:docs

Get a Spelling report

bundle exec rake labdev:lint:spellcheck

Troubleshoot a Jekyll-AsciiDoc build

 # example docs gen
 bundle exec jekyll build --config .config/jekyll.yml --verbose > /tmp/logs/jekyll-build.log 2>&1
 # parse the logs for errors
 bundle exec rake labdev:lint:logs[jekyll,/tmp/logs/jekyll-build.log]

Generate a semantic index/outline of documentation source files

bundle exec rake labdev:skim:adoc[.,tree,json] > .agent/docs/docs-skim.json

Generate an index/outline of Agent-oriented Markdown files (with overlays)

bundle exec rake labdev:skim:md[.agent/docs/:_docs/agent/,tree,json] > .agent/docs/agent-docs-skim.json

Managed Tools

The docopslab-dev gem itself is orchestrated using a manifest file. This manifest declares which tools are active and their integration settings.

Individual configs are maintained for all supported tools in each project codebase. For each project implementation (application) of this coordinating gem, local configs inherit from centrally maintained “canonical” configs that ship with the gem. See File Syncing for details on how the synchronization process works.

Tools Manifest Configuration

Initialization automatically creates .config/docopslab-dev.yml, which you can edit, or you can create it manually.

source:
  repo: DocOps/lab
  ref: v1
docs:
  - source: docs/agent/skills/*.md
    target: .agent/docs/skills/
    synced: true
  - source: docs/agent/topics/*.md
    target: .agent/docs/topics/
    synced: true
  - source: docs/agent/roles/*.md
    target: .agent/docs/roles/
    synced: true

templates:
  manifest:
    - source: templates/AGENTS.markdown
      target: ./AGENTS.md
    - source: templates/gitignore
      target: .gitignore
    - source: templates/README.asciidoc
      target: README.adoc

tools:
  - tool: rubocop
    files:
      - source: rubocop/base.yml
        target: .config/.vendor/docopslab/rubocop.yml
        synced: true
      - source: rubocop/project.yml
        target: .config/rubocop.yml
        synced: false

  - tool: vale
    files:
      - source: vale/base.ini
        target: .config/.vendor/docopslab/vale.ini
        synced: true
      - source: vale/project.ini
        target: .config/vale.local.ini
        synced: false
    paths:
      lint: ['.']
      skip:
        - build/*
        - specs/*
        - .agent/**/*
        - .config/.vendor/**/*
      exts: ['adoc']

  - tool: htmlproofer
    enabled: false  # Disabled by default, enable per project
    files:
      - source: htmlproofer/base.yml
        target: .config/.vendor/docopslab/htmlproofer.yml
        synced: true
      - source: htmlproofer/project.yml
        target: .config/htmlproofer.yml
        synced: false
    paths:
      lint: docs/_site

  - tool: shellcheck
    files:
      - source: shellcheck/base.shellcheckrc
        target: .config/shellcheckrc
        synced: true
  
  - tool: actionlint
    files:
      - source: actionlint/base.yml
        target: .config/.vendor/docopslab/actionlint.yml
        synced: true
      - source: actionlint/project.yml
        target: .config/actionlint.yml
        synced: false

library:
  enabled: true
  source:
    repo: DocOps/lab
    ref: labdev-library

Tools Properties Reference

The following parameters are available for each record in the tools: block of the manifest.

tool

(Slug, required) Name of the tool, ex:, rubocop, vale, htmlproofer, actionlint, shellcheck.

enabled

(Boolean) Whether to enable this tool’s tasks and git hooks.

manifest

(Array of Maps, required) Listing of files to init or sync for the tool. Each entry supports the following properties:

source: (Path, required) Path within the asset library where the base config is located, e.g., config-packs/rubocop/base.yml.
target: (Path, required) Path in the project where the file should be synced, e.g., .config/.vendor/docopslab/rubocop.yml.

paths

(Map) Repo-specific paths to include or exclude in linting operations for this tool.

lint: (Array) List of paths or glob patterns to lint with this tool.
skip: (Array) List of paths or glob patterns to exclude from linting with this tool.
exts: (Array) List of file extensions to include in linting with this tool.
git_tracked_only: (Boolean) Whether to limit linting to only Git-tracked files.

RuboCop

Ruby code style and quality checking.

Base config: .config/.vendor/docopslab/rubocop.yml
Project config: .config/rubocop.yml (inherits via inherit_from)
Sync command: bundle exec rake labdev:sync:configs

The base configuration provides DocOps Lab Ruby style standards. Your project config can override any rule while maintaining consistency with the broader ecosystem.

Vale

Linting for documentation quality and consistency, both AsciiDoc markup syntax and prose quality/correctness.

This tool provides a custom styles package and a modified configuration system, enabling multi-file merging.

Base config: .config/.vendor/docopslab/vale.ini (from source)
Project config: .config/vale.local.ini (inherits via BasedOnStyles)
Ephemeral config: .config/vale.ini (merged from base and target)
Sync command: bundle exec rake labdev:sync:vale

Consumer Mode (Other Projects)

For all other projects, the gem works in a standard package consumption mode:

The project’s vale.ini should list all desired packages, including a URL to the stable, published DocOpsLabStyles.zip.
The labdev:sync:styles task simply runs vale sync in the proper context, downloading all listed packages into a local .vale/styles directory.

The labdev:sync:vale task updates both the base config and the style packages.

A project’s .config/vale.local.ini should look something like the one for this repository (DocOps/lab).

A snippet from DocOps/lab’s .config/vale.local.ini

MinAlertLevel = warning
StylesPath = .vendor/vale/styles

[asciidoctor]
missing-attribute = drop
safe = unsafe
experimental = YES

[_blog/*.adoc]
DocOpsLab-AsciiDoc.ExplicitSectionIDs = NO

[_docs/agent/**/*.adoc]
DocOpsLab-AsciiDoc.ExplicitSectionIDs = NO
DocOpsLab-AsciiDoc.ExtraLineBeforeLevel1 = NO

This dual-mode system provides a robust workflow for both developing and consuming the centralized Vale styles.

For full Vale configuration settings (“keys”) reference, see the official Vale documentation.

HTMLProofer

HTML validation for Jekyll sites and documentation builds.

Base config: .config/.vendor/docopslab/htmlproofer.yml
Project config: .config/htmlproofer.yml
Sync command: bundle exec rake labdev:sync:configs
Enable in manifest: Add htmlproofer tool with enabled: true

HTMLProofer validates links, images, and HTML structure in built sites. Only enabled for projects that generate HTML output (Jekyll sites, etc.).

Base HTMLProofer Configuration

---
# DocOps Lab HTML-Proofer Base Configuration
# This provides sensible defaults for DocOps Lab projects

# URL checking options
check_external_hash: false    # Skip checking external URL fragments (can be slow)
check_img_http: false         # Allow HTTP images for now
enforce_https: false          # Don't enforce HTTPS for all links

# URLs to ignore (patterns and strings)
ignore_urls:
  - /localhost/               # Skip local development URLs
  - /127\.0\.0\.1/           # Skip local IPs  
  - /example\.com/           # Skip example URLs
  - /foo\.bar/               # Skip placeholder URLs
  - /fonts.googleapis.com/   # Skip Google Fonts
  - /fonts.gstatic.com/      # Skip Google Fonts static

# Files to ignore (patterns)
ignore_files:
  - slides/                  # Skip slides directories

# Other options
check_favicon: false         # Don't require favicon
check_html: true            # Check HTML structure
check_opengraph: false      # Skip OpenGraph validation
disable_external: false     # Check external links (can be disabled for speed)

For full HTMLProofer configuration options, see the official docs.

File Syncing

This gem enables central/upstream authorship and maintenance of technical documentation and other flat-file content, with flexible syncing to downstream projects.

Sync Categories

Category Manifest key Primary task(s)

Category	Manifest key	Primary task(s)
Documentation (whole-file)	`docs:`	`labdev:sync:docs`
Tool configs	`tools:`	`labdev:sync:configs`
Scripts	none	`labdev:sync:scripts`
Git hooks	none	`labdev:sync:hooks`
Templates (Sync/Cast)	`templates:`	`labdev:sync:templates`

Documentation (whole-file)

docs:

labdev:sync:docs

Tool configs

tools:

labdev:sync:configs

Scripts

none

labdev:sync:scripts

Git hooks

none

labdev:sync:hooks

Templates (Sync/Cast)

templates:

labdev:sync:templates

Run labdev:sync:all to execute all sync operations in one command.

Types of File-sync Operations

The docopslab-dev tool supports two main types of syncing operations, each with different use cases and behaviors.

whole-file syncing: Maintain a local copy of centrally managed files like developer documentation, tool configs, and automation scripts. This is the main syncing pattern.
template sync casting: Maintain canonical sections of code or text in files that need to be partially customized but also regularly updated from a central source.
stub initialization: This is actually just an instance of casting that is not kept in sync after being written to the codebase during an init operation.

File Syncing Semantics

Files are kept in sync under the following categorical semantics:

documentation (docs): Whole directories of documentation files that are authored in the DocOps/lab repo and synced to projects using rake labdev:sync:docs.
tool configuration files (configs): Files tied dependency tools like Vale and RuboCop. Synced using rake labdev:sync:configs.
scripts: All files in scripts/.vendor/ path (rake labdev:sync:scripts).
Git hooks (hooks): All Git hooks from the assets library (rake labdev:sync:hooks).
linter styles/rules (styles): Specific rulesets mapped to linters, including third-party origins.
Vale linter (vale): Includes Vale styles and config, together (rake labdev:sync:vale).
Liquid/casting templates: Files that are rendered using Liquid syntax and/or canonical block resolution. Uses rake labdev:sync:templates or rake labdev:sync:templates[.gitignore] for a specific file.

The command rake labdev:sync:all performs all syncing operations in one go.

Whole-file Syncing Operations

When we talk about “whole file” vs “templated” file syncing, we refer strictly to the relationship with upstream/centralized canonical sources. Even whole-file syncing does not mean the downstream version of such files are what affects the system.

Configs can generally be merged with local settings, whereas documents and scripts tend to be replaced by local alternates.

Cross-project Documentation

The gem manages LLM/agent-oriented documentation that can be synced to downstream projects for local availability. Some files and paths are highlighted here.

Specific instruction files for AI agents working with common tools and patterns. For instance, local paths:

.agent/skills/git.md
.agent/skills/fix-spelling-issues.md
.agent/missions/conduct-release.md

Such files are sourced as AsciiDoc in DocOps/lab/_docs/agent/, largely reusing content from people-facing docs sourced in _docs/reference/ and _docs/tasks/.

In most contexts, agents are instructed to check for a parallel file in the local project’s docs/ directory that would supersede the locally synced copy.

Tool Configs and Scripts

Tool configs, linter styles, scripts, and Git hooks are all synced as part of labdev:sync:all. Most have no per-project manifest configuration; they are sourced from the centrally managed library and written to conventional paths.

Configs and linter styles: Synced by labdev:sync:configs, labdev:sync:vale, labdev:sync:styles, and labdev:sync:all, depending on intent.

These types of files are generally merged with existing local versions, rather than replaced, to preserve any project-specific customizations while still applying updates from the central source.
Scripts: Synced to scripts/.vendor/docopslab/ using labdev:sync:scripts. Local overrides placed at scripts/ take precedence over upstream versions of the same filename, though of course they can execute the upstream-sourced scripts.
Git hooks: Synced to .git/hooks/ with labdev:sync:hooks. Git hooks do not have a merge or override system; they are either present or not.

Template Sync Casting

While most docopslab-dev file-sync operations are standard (whole-file replacement), the concept of sync casting deserves more attention.

Template sync casting keeps project files (targets) up to date with upstream canonical source templates (primes) using the AsciiSourcerer::Sync::Cast model and engine.

Casting can swap whole blocks of code, and it can render Liquid syntax, on a one-time or ongoing basis.

Liquid can be used anywhere in the source/prime template. It will be processed during init operations for full rendering of the initial file.

During sync operations, casting will render Liquid syntax in canonical block content only.

Liquid Context

While the canonical blocks are sourced right in the source template file, data used to render Liquid-tagged content must come from an external source.

runtime variables: At runtime, project attributes are derived from the README.adoc file and made available to all templates as {{ data.project.attributes.<attr_key_name> }}.
manifest assignment: Data objects (variables) can be defined in the manifest, alongside a given instance of the mapping. These are available as {{ data.variables.<object> }} in the template, where <object> is the name of a String, Boolean, Number, Array, or Map variable type.
local/inherited assignment: Standard Liquid variables established with {% assign %} or `{% capture %} tags in templates or arguments passed to Jekyll-style {% include %} tags.

Operations

Two operations are available:

labdev:init:templates: Bootstrap new target files from their source templates. During init, the entire source template is rendered through Liquid before writing, so every {{ data.project.attributes.name }} or {{ data.variables.my_key }} placeholder anywhere in the document is resolved. Targets that already exist are skipped.
labdev:sync:templates: Update canonical blocks in existing target files from the source template. During sync, only the content inside canonical blocks is rendered through Liquid. Content outside blocks is sourced from the target, not the source template, so template syntax outside blocks is never touched.

Bootstrap all configured targets

bundle exec rake labdev:init:templates

Sync all configured targets

bundle exec rake labdev:sync:templates

Sync a single target (by its target path)

bundle exec rake 'labdev:sync:templates[AGENTS.md]'

Preview a single target without writing

bundle exec rake 'labdev:sync:templates[AGENTS.md,dry]'

The bulk sync is also included in labdev:sync:all.

Manifest Configuration

This reference covers the properties relevant to file syncing and sync casting in the manifest file at .config/docopslab-dev.yml.

The docs: block in the manifest is itself a manifest array. Each entry supports the following properties:

source

(Path, required) Source path relative to lib/docopslab/ in the gem. Supports glob patterns (e.g., docs/agent/*.md) or specific files.

target

(Path, required) Target path relative to the project root. Can be a directory (e.g., _docs/) or specific file path (e.g., AGENTS.md).

synced

(Boolean) Whether to update existing files on sync.

true - Always overwrite on sync (keeps docs current with gem updates)
false - Create once, preserve user customizations

The templates: block in the manifest is a Map that nests its own manifest: listing as well as global data ingestion directives in data:.

manifest

(Array) Listing of prime templates and their downstream target files for Sync/Cast operations, optionally passing additional data.

source: (String) The path to the source template file, library relative (resolved via labdev:sync:library).
target: (String) The path in the project where the rendered template should be synced, relative to the project root.
data: (Map) Optional additional data to pass to the template rendering process.
data.variables: (Map) Key-value pairs of variables bearing any value type to pass to the template rendering process, accessible as {{ data.variables.<key> }} in templates.

Template Manifest Configuration

Entries are declared under the templates.manifest: key in .config/docopslab-dev.yml. The key takes a Hash with two children: a global data: node and a manifest: list.

templates:
  data:                          # Global data available to all entries
    variables:
      project_name: "My Project"
  manifest:
    - source: templates/AGENTS.markdown   # Library-relative source template path
      target: AGENTS.md                   # Project-local target path
    - source: templates/custom.adoc
      target: docs/custom.adoc
      data:                               # Per-entry overrides, merged on top of global
        variables:
          extra_key: "value"

For a full property reference, see the comments in specs/data/default-manifest.yml in the gem source.

Liquid Template Context

All Liquid variables are scoped under the top-level data key:

data.project.attributes.<key>: Document attributes loaded from the project’s README.adoc header. Asciidoctor built-in attributes are filtered out; only user-defined string attributes are available.
data.variables.<key>: Merged from global data.variables and the per-entry data.variables override. Per-entry values take precedence.

{{ data.project.attributes.this_proj_name }}
{{ data.variables.description }}

During init, Liquid is rendered across the entire source template, so all {{ data.* }} references anywhere in the file are resolved. During sync, only the content inside canonical blocks is rendered; template syntax outside blocks is intentional scaffolding and will never be evaluated.

Block Syntax

Canonical blocks use the same AsciiDoc tag syntax as the rest of the DocOps Lab toolchain, wrapped in file-appropriate comments.

AsciiDoc / Markdown (HTML comment wrapper)

This content is managed in the source template.

AsciiDoc (native comment)

This content is managed in the prime template.

The canonical_prefix: setting controls which tagged blocks are treated as canonical. By default this is universal-. A target may contain alternate-prefixed blocks (e.g. local-agency) as a cue to the engine that a canonical block has been intentionally replaced; no warning is emitted for those.

Typical Workflow

The expected workflow for a new project:

Register the entry in .config/docopslab-dev.yml under templates.manifest.
Run labdev:init:templates to bootstrap the target file.
Customize the project-specific sections (outside canonical blocks).
As the source template evolves upstream, run labdev:sync:templates to pull in updated canonical blocks without disturbing local content.

Remote Asset Library

The docopslab-dev fetches a centrally managed asset library from the labdev-library branch of DocOps/lab and caches it host-wide at ~/.cache/docopslab/dev/library/. This enables updates per-project updates to config packs, templates, docs, hooks, and scripts without needing to update the gem package or re-download the remote library.

Cache Layout

The library cache lives at ~/.cache/docopslab/dev/library/ (or under $XDG_CACHE_HOME/docopslab/dev/library/ if that variable is set):

~/.cache/docopslab/dev/library/
  current/          # Active snapshot used by sync and resolve operations
    catalog.json    # Catalog with version, ref, and checksums
    config-packs/
    docs/
    hooks/
    scripts/
    templates/
  previous/         # Prior snapshot retained for fast rollback

Updates are never automatic. Run labdev:sync:library explicitly to pull a new snapshot. The prior snapshot is preserved as previous/ so a broken update can be rolled back immediately.

On first use, sync operations auto-fetch the library if no cache exists.

Library Configuration

Add a library: block to .config/docopslab-dev.yml to configure the source. All fields are optional; defaults target the labdev-library branch of DocOps/lab.

library:
  enabled: true
  source:
    type: git-branch
    repo: DocOps/lab
    ref: labdev-library
    path: library
  sync:
    mode: latest-only
    cache_root: ~/.cache/docopslab/dev/library
  # Optional: local fallback path when XDG cache is absent.
  # Populated by `bundle exec rake gemdo:push:library:stage` in DocOps/lab.
  local_path: .library

Library Tasks (Consumer Projects)

Fetch and cache the latest remote library

bundle exec rake labdev:sync:library

Show current library cache status and version

bundle exec rake labdev:show:library

The fetch tasks require either the gh CLI or git to be available on your PATH. The gh CLI is preferred and will be used when present.