Canonical Web Agents Pack

Opinionated starter templates for a 5-agent web development lifecycle:

1. Spec Agent
2. Builder Agent
3. Verifier Agent
4. Reviewer Agent
5. Release Agent

Structure

• agents/: role contracts for each agent
• skills/: five skills (specify/, implement/, verify/, review/, ship/, each with SKILL.md) + REGISTRY-NOTES.md (alignment with skills.sh-style discoverability)
• schemas/: JSON schemas for agent outputs
• workflow/: gate policy and lifecycle orchestration

Quick Start

1. Read workflow/workflow.md.
2. Start with agents/spec-agent.md.
3. Have each agent produce outputs matching its schema in schemas/.
4. Enforce the gates in workflow before merge/deploy.
5. Validate artifacts:
   • Reference examples: python scripts/validate_artifacts.py
   • A run folder: python scripts/validate_artifacts.py runs/<feature>
   • Require all five files in a run: python scripts/validate_artifacts.py runs/<feature> --strict

Output Contract Chain

• Spec Agent -> spec.json
• Builder Agent -> build_report.json (includes pull_request: URL and branch fields for the reviewable PR)
• Verifier Agent -> verification_report.json
• Reviewer Agent -> review_decision.json
• Release Agent -> release_report.json

Each artifact must include metadata and a stage linkage reference to its direct upstream artifact.

Rules

• No implementation without a valid spec.json.
• No release when verification or review is blocked.
• Every block must include evidence and remediation steps.

Examples

Reference example artifacts are in examples/ and are validated by:

python scripts/validate_artifacts.py

Install into another project (no Make)

This repository keeps the pack at the root (agents/, schemas/, scripts/, …). The name agent-pack is not a folder here — it is only the default subdirectory name used when you copy the pack into another project (override with --prefix).

/path/to/this-repo/scripts/install-into-project.sh /path/to/host-project
/path/to/this-repo/scripts/install-into-project.sh --prefix tools/web-agents /path/to/host-project

Optional: add GitHub Actions that run inside the installed folder (working-directory is set to your prefix):

/path/to/this-repo/scripts/install-into-project.sh --with-github /path/to/host-project

That writes two workflow files under the host’s .github/workflows/, named from your prefix (slashes become hyphens), for example agent-pack-validate-agent-artifacts.yml and agent-pack-issue-run-stub.yml. Re-run with --force to refresh.

From the host project root, validate examples (default prefix):

python agent-pack/scripts/validate_artifacts.py

Submodule (alternative): add this repo as a submodule at e.g. agent-pack/ and skip the installer; adjust paths to match that directory name.

GitHub issues

Opening an issue triggers a workflow that adds runs/issue-<number>/README.md (see .github/workflows/issue-run-stub.yml). Put your stage artifacts in that folder.