Agentic Coding Maintainers

Internal tools, runbooks, and automation for GSA-TTS agentic-coding maintainers. This repository is the canonical home for both included skills after their initial reviewed imports.

Included Skills

The skill at .agents/skills/cross-repo-epic provides read-only portfolio and epic reconciliation for the agentic-coding repositories. See its SKILL.md for requirements and use instructions.

The skill at .agents/skills/workspace-orchestrator provides reusable, host-side coordination for multiple implementation/review workstreams: bounded worker admission, one-writer worktrees, fixed-head QA/security review, foreground GitHub monitoring, and fail-closed recovery. It accepts arbitrary GitHub repositories and an optional Project v2 board through validated consumer configuration. It is not an acq guest kit or a sandbox boundary.

Both skills use the portable Agent Skills layout and are tested with OpenCode 1.19+ and 2.0+. See docs/OPENCODE-COMPATIBILITY.md for verified interfaces, provider-config differences, and model-free runtime probes.

Provenance And Sync

The skill originated in the source author's review_things repository and was hardened in the agentic workspace. Its PROVENANCE.md records the authorized source commit and destination adaptations. Keep that record when moving or revising the skill.

After this repository's initial import, make authoritative changes here. The old scripts/import-review-things.sh expected skill files at obsolete root paths in review_things and could no longer import them. It was removed rather than encouraging a broken, backwards import from a consumer into the canonical repository. The original authorized import remains documented in each skill's PROVENANCE.md.

The workspace-orchestrator import is separate because its source includes multiple binaries, role profiles, tests, and docs:

IMPORT_DIR="$(scripts/import-workspace-orchestrator.sh /path/to/review_things | sed -n 's/^STAGED=//p')"
diff -ru "$IMPORT_DIR" .agents/skills/workspace-orchestrator

The import records SHA-256 for every staged source file. After initial import, this repository is canonical; do not automatically overwrite reviewed destination adaptations with a newer workspace copy.

The agentic workspace consumes these skills at agentic/.agents/skills/<skill-name>. From this repository, update one selected copy with:

scripts/sync-agentic-workspace.sh /path/to/agentic cross-repo-epic
scripts/sync-agentic-workspace.sh /path/to/agentic workspace-orchestrator

Each successful sync prints DISPOSAL_OUTBOX=. The replaced skill tree and this invocation's lock/marker live in a manifest-backed tmp/cleanup/<uuid>/ entry in the consumer workspace, alongside owner-selected loose-file quarantine. Git consumers must ignore root /tmp/ and have no HEAD/index paths there before sync; non-Git consumers use the same private directory convention. Sync preserves MANIFEST.md, backups and pre-existing uncertain markers. It does not delete artifacts. Use the single workspace cleanup round to inventory these entries; legacy deleteme/ requires an explicit maintenance window migration, never an automatic move or a second ongoing process.

The script stages then replaces only the selected canonical skill directory, with a transaction marker and trap that restores the previous copy if interrupted before installation completes. The brief two-rename replacement is not a cross-platform atomic exchange. An atomic per-skill lock refuses concurrent or uncertain stale transactions; process death outside trap handling requires human inspection rather than automatic takeover. It cannot delete a sibling skill. Review the destination diff, run every applicable fixture suite for the selected skill, and record this repository's canonical commit in the destination PROVENANCE.md.

Do not sync runtime state or review artifacts. In particular, exclude secrets, Nexus records, certificate authority bundles, handoffs and unposted issue drafts. Reviewed maintainer runbooks and nonsensitive operating records may live here; check their contents, not only their filenames.

Development

Releases and deployment direction

The first intended source release is v0.1.0. The initial version.txt value 0.0.0 is a bootstrap sentinel, not a published release. Release generation is operator-gated and uses Release Please with GITHUB_TOKEN; bot PRs need human close/reopen to start normal CI when current-head checks are missing. See the release lifecycle and changelog.

The deployment target is the full maintainer workspace and orchestrator inside an MSB VM, with real rootless inner-OCI execution. OpenCode is the first reference harness, then Pi. This groundwork does not qualify those deployments or claim a stable 1.0 contract. See the acceptance plan and support matrix.

Run maintainer work from this repository

The skills are self-contained. For this engagement, copy orchestrator.example.json to the gitignored orchestrator.json and review its repository list and Project board before using it. The default example does not become live configuration automatically.

bin/orchestrator-state.sh reconcile
bin/orchestrator-state.sh list
bin/portfolio-status.sh
bin/epic-status.sh patterns#357
# After creating a kind=monitor task named portfolio-monitor, claim and exec
# in the SAME process (the recorded worker PID must be the monitor's PID):
sh -c 'bin/orchestrator-state.sh claim portfolio-monitor --owner monitor --pid $$ >/dev/null && exec bin/orchestrator-monitor.sh --task-id portfolio-monitor --loop'

The bin/ scripts are thin entry points into the canonical skills. A missing monitor config exits 3 (UNVERIFIED). Keep .orchestrator/ task records, work/ task worktrees, clones/ upstream clones, and orchestrator.json host-local and uncommitted. .opencode/agents/ contains installed copies of the canonical role profiles; the test suite checks their byte equality. Restart OpenCode after changing agents or commands.

See AGENTS.md for worker limits, ownership, recovery and the trust boundary: a worktree is not a sandbox for untrusted PR code.

After task handoff, inventory loose root artifacts and the shared cleanup store:

bin/workspace-cleanup.sh --workspace /absolute/workspace

Inventory is read-only. Quarantine and restore preview unless --apply is given; neither accepts directories or batches, and there is no purge command. See docs/WORKSPACE-CLEANUP.md for ownership checks, recovery limits and the unified skill-sync outbox process.

Checks

For an operator-invoked, read-only current-state task-record scorecard, run python3 -I -B scripts/evaluate-workflow.py --workspace .. See docs/WORKFLOW-EVALUATION.md for its unmeasured outcomes, cohort design and reflection guardrails. An empty or unreadable task store exits 3 (UNVERIFIED), never a healthy-looking zero-work report.

The first recorded-cohort reflection parser is python3 -I -B scripts/cohort-reflection.py --ledger /absolute/private/cases.jsonl --key-file /absolute/private/report.key --inventory /absolute/private/requests.json --required-source issue-feed --as-of <UTC>. Its contract distinguishes recorded events from independently verified outcomes; it cannot infer intake completeness or verified completions from the ledger alone.

For conditional intake coverage, supply a separately captured private request inventory and predeclare each expected source using --required-source. See docs/INTAKE-INVENTORY.md; even a complete source flag is an attestation, not proof that every real-world request was captured.

To record one sanitized local event, initialize a private ledger outside git and use python3 -I -B scripts/append-cohort-event.py --ledger /absolute/private/cases.jsonl with a JSON event on stdin. See docs/COHORT-APPEND.md for the exact initialization, locking, failure and evidence limits.

make test
make check

make check uses ShellCheck when it is already installed. It does not download tools.

Core CI tools on Linux

tools/install-ci-tools.sh /absolute/path/to/ci-tools installs exactly six core tools: Ruff, Pyright, Bandit, ShellCheck, actionlint, and zizmor. Run it only inside an independently justified workspace sandbox. It downloads pinned artifacts and requires a glibc-based Linux x86_64 or ARM64 (uname -m = aarch64) environment, Python 3.12 with venv/pip support, Node.js/npm, Bash, curl, sha256sum, tar with gzip/xz support, and standard file utilities. macOS, other architectures, and musl-based Linux are not supported. The platform case rejects unrecognized OS/architecture pairs before destination or temporary directory writes; it does not detect the libc. The Python version check also precedes those writes. Add the absolute destination's bin/ to PATH afterward.

Native archives are SHA-256 checked before extraction. Bandit uses separate seven-package hash locks for x86_64 and aarch64; only the Python 3.12 manylinux PyYAML wheel hash differs. Pyright uses the existing npm lock with install scripts disabled. Temporary downloads are private and cleaned on exit, but failure may leave an incomplete destination; installation is not atomic.

The ARM64 archive pins were supplied from independently obtained upstream GitHub asset digests; the PyYAML 6.0.3 CPython 3.12 manylinux aarch64 wheel pin was supplied from PyPI JSON. Offline fixtures check the selected URLs, pins, lock, ordering, rejection and failure behavior with synthetic command stubs; they do not download or execute upstream tools, verify upstream availability, or qualify native ARM64 execution. Run python3 -I -B tests/ci-tool-installer-test.py inside the sandbox (also included in make test and make check).

This is not a full strict-tool bootstrap: pre-commit, Gitleaks, and Trivy are separate prerequisites for make strict-check / pre-commit run --all-files. Their required versions, along with the core tools, are recorded in tools/precommit-versions.json.

Repository administrators must complete and verify docs/REPOSITORY-SETUP.md after bootstrap. Maintainers troubleshooting GitHub Actions log downloads on managed macOS hosts should use docs/MACOS-GITHUB-TLS.md.

License

This repository is dedicated to the public domain under CC0 1.0 Universal. See LICENSE. Source provenance is retained for audit and attribution context.