magnus919_agent-skills/docs/bundle-manifest-design.md

Bundle Manifest Design — Issue #203

This note records the design decision for the bundle-manifest contract and the lifecycle capability matrix introduced for issue #203 ("chore: define bundle manifests and lifecycle capability matrix"). It is the bounded design note required by acceptance criterion AC1: it surveys the repository's existing bundle metadata, records the chosen schema, and explains why the chosen field set is the smallest set that still covers the required contract. It deliberately does not propose a second skill format, does not require top-level skills to join bundles, and does not expand into unrelated repository refactors (see Non-goals).

1. Problem statement

The repository has eight canonical bundles — top-level directories with a SKILL.md entrypoint: product-lifecycle, production-excellence, agent-production-operations, forward-deployed-engineering, neckbeard, workflow-architect, tailscale, and research-and-vault. Only workflow-architect carries a bundle-metadata concept today, and that concept is generation-time configuration for its own builder — not a common, machine-readable composition contract. Users and agents cannot consistently discover, from metadata alone, what a bundle is for, which lifecycle stages it covers, which skills it composes, what it requires, what it produces, where it hands off, where it overlaps other bundles, and how it is evaluated.

2. Survey of existing bundle metadata

2.1 workflow-architect/templates/manifest.yaml.tmpl

The template defines a generation-time manifest with the following fields:

Field	Meaning
bundle_name	Bundle identity for the generator
generated	Generation date (timestamp)
archetype	Builder archetype (e.g. morning-triage-deep-work)
kanban (optional)	Kanban board metadata (board_slug, phases)
skills	Ordered list of {name, file, trigger{type, keywords, description, context}}

Its purpose is to drive the workflow-architect generator (morning-triage / deep-work archetypes, kanban boards). The skills entries describe loading triggers (keyword → nested skill) for that specific builder — not a general capability contract.

2.2 workflow-architect/references/example-output/developer-triage/manifest.yaml (and developer-pipeline-kanban)

Concrete instances of the template: bundle_name, generated (e.g. 2026-05-29), archetype (morning-triage-deep-work, build-review-deploy), optional kanban (developer-pipeline-kanban only), and skills entries with trigger metadata (type: keyword / keyword+context, keywords, description, optional context). These confirm that the existing manifest concept is workflow-architect-specific generation configuration — no bundle outside workflow-architect consumes it.

2.3 Bundles that carry no manifest today

neckbeard/, research-and-vault/, and tailscale/ carry no manifest of any kind. Their capability description lives only in the SKILL.md frontmatter description field. product-lifecycle, production-excellence, and agent-production-operations (the three new milestone bundles) also carry no manifest today; they ship one with this issue.

2.4 open-knowledge-format/references/bundle-architecture.md

OKF's bundle-architecture describes organizational guidance for knowledge bundles: flat vs. hierarchical directory layouts, index.md design, cross-linking patterns, and tagging conventions. It is not a machine-readable manifest format and defines no schema; it informs how bundles are organized, not how their capabilities are declared.

2.5 Survey conclusion

The existing "manifest" concept is (a) workflow-architect-specific, (b) generation-time configuration rather than a capability contract, and (c) not consumed by any other bundle or tool. OKF contributes structure guidance but no schema. No existing artifact exposes the discovery contract this issue needs (purpose, audience, stages, included skills, prerequisites, outputs, handoffs, conflicts, eval suite) in a machine-readable form. A new, small, versioned schema is therefore warranted — it reuses the repository's schema conventions (schemas/evals-v1.schema.json: JSON Schema, versioned filename *-v1.schema.json) rather than inventing a parallel mechanism.

3. Chosen schema

The contract is schemas/bundle-manifest-v1.schema.json (JSON Schema, draft 2020-12, additionalProperties: false, versioned filename following the evals-v1.schema.json convention). A manifest lives at <name>/manifest.yaml and is validated by scripts/validate-bundles.rb.

3.1 Fields preserved, dropped, and renamed vs. the existing manifest concept

Existing concept (workflow-architect)	Disposition	Rationale
bundle_name	Preserved (renamed semantics: now must equal the bundle directory name)	Bundle identity is required for cross-references and the matrix
skills list	Renamed → included_skills	Entries become relative SKILL.md paths (catalog references or nested helpers) instead of trigger configurations; a machine-checkable composition list
trigger {type, keywords, ...}	Dropped	Loading triggers remain human-authored prose in each bundle's SKILL.md / AGENTS.md, where they are read; the manifest is a capability contract, not a loader config
generated (timestamp)	Dropped	Generation-time metadata; a timestamp would make the generated matrix non-deterministic
archetype	Dropped	workflow-architect-specific concept with no meaning for the other bundles
kanban {board_slug, phases}	Dropped	Pipeline-board-specific concept owned by workflow-architect's builder
(new) purpose, audience, stages, prerequisites, outputs, handoffs, conflicts, eval_suite, schema_version	Added	The nine contract fields + version pin, below

3.2 The nine contract fields and the minimalism rationale

The issue contract names nine fields. Each maps to exactly one discoverability question a user or agent must be able to answer from metadata alone; no field can be derived from another, and dropping any one leaves a question unanswerable:

#	Field	Question it answers	Consumer
1	purpose	What does this bundle do?	Human readers, matrix, catalog
2	audience	Who is this for?	Human readers, matrix
3	stages	What lifecycle span does it cover, and which skill serves each stage?	Lifecycle discovery (VAL-MNF-018)
4	included_skills	Which skills does it compose? (paths resolve to SKILL.md files)	Composition boundary, catalog-exactness (VAL-MNF-020)
5	prerequisites	What inputs/artifacts must exist before use, and from which skills?	Readiness-path discovery (VAL-MNF-019)
6	outputs	What artifacts does it produce?	Handoff validation (VAL-MNF-014)
7	handoffs	Where do its outputs go next?	Composition navigation, conflict analysis
8	conflicts	Where does it overlap another bundle/skill, and how should overlap route?	Conflict resolution (VAL-MNF-021)
9	eval_suite	How is it evaluated, and where is the eval manifest?	Eval discovery (VAL-MNF-017)

Why this is the smallest set: every field is either (a) an irreducible answer to a discovery question the issue explicitly requires, or (b) a reference used by the validators to reject contradictory metadata. The schema adds only schema_version and bundle_name (identity + version pin, mirroring evals-v1). It deliberately excludes workflow-architect's trigger/archetype/ kanban machinery, excludes free-form "tags" (already present in SKILL.md frontmatter metadata), and excludes per-skill methodology content (owned by the skills themselves). Each field has a defined type (strings, ordered stage lists, path lists) chosen so that a validator can machine-check completeness and consistency without a second toolchain.

4. Migration path

Per the milestone-4 mission boundary, the four pre-existing canonical bundles are off-limits in this issue — their metadata belongs to their owning areas and must not be changed here. They are therefore listed in this migration path with a stated reason and future sequencing:

Bundle	Status this issue	Reason (mission boundary)	Future sequencing
workflow-architect	No manifest added	Already owns a manifest concept (generation config for its builder); converting it to the new contract would require migrating the builder and its example-output fixtures, which is out of scope for #203	Convert after its builder tooling and example-output fixtures are stable; preserve trigger semantics in SKILL.md/AGENTS.md prose
neckbeard	No manifest added	Ships its own evaluation harness (eval/) and delivery-packet lifecycle; belongs to the neckbeard maintenance track	Add a manifest on its next substantive change, deriving stages from its journey phases
tailscale	No manifest added	Complex multi-skill bundle with its own skills/ hierarchy and scripts; belongs to the tailscale maintenance track	Add a manifest when its nested-skill boundary is next documented, listing nested helpers under skills/
research-and-vault	No manifest added	Minimal bundle (SKILL.md + README only) with no composition surface yet	Add a manifest when it gains references/helpers

The three new milestone bundles — product-lifecycle, production-excellence, and agent-production-operations — and forward-deployed-engineering ship schema-conformant manifest.yaml files now (<name>/manifest.yaml), each resolving eval_suite to its own <name>/evals/evals.json.

For the matrix, bundles without a manifest are rendered with a purpose derived from their SKILL.md frontmatter description and the remaining cells set to the documented deferral marker migration deferred — see docs/bundle-manifest-design.md §Migration path (never blank; see VAL-MNF-010/011).

5. Non-goals

• No second skill format. The manifest contract does not alter the top-level SKILL.md format: validate-skills.rb's ALLOWED_FIELDS (name description license compatibility metadata allowed-tools) is unchanged, and no validator requires a manifest for a top-level <skill>/SKILL.md. Manifests are not registered as standalone skills in any catalog.
• No mandatory bundle membership. Bundles remain optional composition layers. Top-level skills that belong to no bundle continue to validate, appear in catalogs, and are never flagged for lacking a manifest or bundle membership. No validator contains an error path of the form "must belong to a bundle".
• Capability descriptions stay in source. Each bundle's human-readable capability description remains discoverable from source metadata (the SKILL.md description field and/or the manifest purpose field), independent of the generated matrix. Deleting the generated matrix loses no capability description.
• No unrelated refactors. This issue touches only the changed surface listed in the PR: {product-lifecycle,production-excellence, agent-production-operations}/** (additive manifest + doc rows), schemas/, scripts/, docs/, and .github/workflows/validate.yml.

6. Validation and generation

• scripts/validate-bundles.rb — rejects incomplete manifests (missing required field, naming the file and field), contradictory manifests (unresolvable included_skills, handoff naming an undeclared output/stage, conflict naming a non-catalog skill), dangling eval_suite references, and undeclared cross-bundle overlaps on included skills (naming both manifests).
• scripts/gen-lifecycle-matrix.rb — deterministically generates docs/lifecycle-capability-matrix.md (one row per canonical bundle) and docs/lifecycle-capability-matrix.json (machine-readable, per-cell source provenance), reusing the gen-*.rb generator conventions (ROOT, PUBLIC_SKILLS, YAML.safe_load frontmatter parsing, --write mode, check mode with a Run: ruby scripts/gen-lifecycle-matrix.rb --write hint).
• scripts/validate-lifecycle-matrix.rb — verifies the JSON artifact covers every canonical bundle, every populated cell traces to its source, the artifact is current, and nested bundle helpers never leak into the four generated catalogs.
• scripts/test-validate-bundles.rb — deterministic positive/negative test coverage for the validator, generator, and matrix validator.
• .github/workflows/validate.yml — runs the new validator, tests, generator check, and matrix validator as part of the repository gate suite.