feat: add agent instructions artifact bundle handoff (#86)

Author: tkstang

.agents/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.7.0
+version: 1.9.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
@@ -37,8 +37,13 @@ Scan, evaluate, and report on agent instruction file coverage, quality, and drif
 ## Analyze vs Apply Boundary
 
 `oat-agent-instructions-analyze` owns discovery, evaluation, evidence gathering, and recommendation shaping.
-The analysis artifact must be detailed enough that `oat-agent-instructions-apply` can execute approved
-recommendations without rediscovering repo conventions from scratch.
+Its output now has two layers:
+
+- a human-readable review artifact (`agent-instructions-<timestamp>.md`)
+- a machine-oriented companion bundle (`agent-instructions-<timestamp>.bundle/`)
+
+The markdown artifact is for reviewers. The bundle is the generation contract that `oat-agent-instructions-apply`
+should consume when it exists.
 
 `oat-agent-instructions-apply` may verify that cited files still exist and may read those same cited
 sources while generating output, but it must not invent unsupported conventions, create new recommendations,
@@ -390,11 +395,35 @@ Generate the analysis artifact using the template at `references/analysis-artifa
 ```bash
 TIMESTAMP=$(date -u +"%Y-%m-%d-%H%M")
 ARTIFACT_PATH=".oat/repo/analysis/agent-instructions-${TIMESTAMP}.md"
+BUNDLE_DIR="${ARTIFACT_PATH%.md}.bundle"
+SUMMARY_PATH="${BUNDLE_DIR}/summary.md"
+MANIFEST_PATH="${BUNDLE_DIR}/recommendations.yaml"
+PACKS_DIR="${BUNDLE_DIR}/packs"
+mkdir -p "$PACKS_DIR"
 ```
 
 Fill in all template sections with findings from Steps 2-7.
 
-The artifact is the contract for apply. It must contain:
+Write the human-readable markdown artifact to `$ARTIFACT_PATH`.
+
+Also write the companion bundle to `$BUNDLE_DIR` with this layout:
+
+- `summary.md` — rendered from `references/bundle-summary-template.md`
+- `recommendations.yaml` — rendered from `references/recommendations-manifest-template.yaml`
+- `packs/<recommendation-id>.md` — rendered from `references/recommendation-pack-template.md`
+
+Bundle contract requirements:
+
+- every recommendation gets a stable `Recommendation ID` (for example, `rec-001`)
+- the markdown artifact, manifest, and pack filenames must agree on that ID
+- `recommendations.yaml` must include each recommendation's ID, target, action, disclosure, severity/confidence, and
+  relative `pack` path
+- each pack must preserve the recommendation's evidence refs, structural conventions, behavioral conventions,
+  counter-examples, new-file workflow, preferred default, and claim corrections
+- if the markdown artifact and bundle ever diverge, the bundle is the apply contract and the markdown artifact is the
+  review summary
+
+The markdown artifact and companion bundle together are the contract for apply. They must contain:
 
 - exact evidence references for each finding and recommendation
 - confidence for each recommendation
@@ -403,8 +432,7 @@ The artifact is the contract for apply. It must contain:
 - claim-correction details when updating or contradicting existing rules
 - content-guidance fields (`Must Include`, `Must Not Include`, `Preferred Default for New Files`) for any
   recommendation that requires judgment during generation
-
-Write the artifact to `$ARTIFACT_PATH`.
+- stable recommendation IDs and pack references for any recommendation that apply may execute
 
 ### Step 9: Update Tracking and Output Summary
 
@@ -441,6 +469,7 @@ Analysis complete.
     Low:       {N}
 
   Artifact: {artifact_path}
+  Bundle:   {bundle_dir}
 
 Next step: Run oat-agent-instructions-apply to act on these findings.
 ```
@@ -461,6 +490,9 @@ Next step: Run oat-agent-instructions-apply to act on these findings.
 - Directory criteria: `references/directory-assessment-criteria.md`
 - File-type discovery: `references/file-type-discovery-checklist.md`
 - Artifact template: `references/analysis-artifact-template.md`
+- Bundle summary template: `references/bundle-summary-template.md`
+- Bundle manifest template: `references/recommendations-manifest-template.yaml`
+- Recommendation pack template: `references/recommendation-pack-template.md`
 - Tracking script: `scripts/resolve-tracking.sh`
 - Provider resolution: `scripts/resolve-providers.sh`
 - File discovery: `scripts/resolve-instruction-files.sh`

.agents/skills/oat-agent-instructions-analyze/references/analysis-artifact-template.md

@@ -14,6 +14,20 @@ oat_analysis_commit: { commitHash }
 **Providers:** {agents_md, claude, cursor, ...}
 **Commit:** {short-hash}
 
+## Bundle Outputs
+
+The companion bundle for this analysis lives beside the markdown artifact and is the primary generation contract for
+`oat-agent-instructions-apply` when present.
+
+| Path                                | Purpose                                       |
+| ----------------------------------- | --------------------------------------------- |
+| `{artifact-path}`                   | Human-readable review artifact                |
+| `{bundle-dir}/summary.md`           | Compact bridge summary for apply-time context |
+| `{bundle-dir}/recommendations.yaml` | Manifest of executable recommendations        |
+| `{bundle-dir}/packs/`               | Recommendation-scoped packs                   |
+
+Every recommendation below should include a stable `Recommendation ID` that maps to exactly one pack file.
+
 ## Summary
 
 - **Files evaluated:** {N}
@@ -173,8 +187,10 @@ Capture which details should live in always-on instructions versus linked docume
 Prioritized actions based on findings above.
 
 1. **{Action}** — {rationale} (addresses finding #{N})
+   - Recommendation ID: `rec-001`
    - Target: `{path}`
    - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-001.md`
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
@@ -185,8 +201,10 @@ Prioritized actions based on findings above.
    - Preferred Default for New Files: {pattern A / pattern B / N/A}
    - Claim Corrections: {`old claim -> verified replacement` or `none`}
 2. **{Action}** — {rationale} (addresses provider baseline gap #{N})
+   - Recommendation ID: `rec-002`
    - Target: `{path}`
    - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-002.md`
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
@@ -197,8 +215,10 @@ Prioritized actions based on findings above.
    - Preferred Default for New Files: {pattern A / pattern B / N/A}
    - Claim Corrections: {`old claim -> verified replacement` or `none`}
 3. **{Action}** — {rationale} (addresses gap #{N})
+   - Recommendation ID: `rec-003`
    - Target: `{path}`
    - Provider/Format: {provider / format}
+   - Bundle Pack: `{bundle-dir}/packs/rec-003.md`
    - Evidence: {exact refs}
    - Confidence: {high | medium | low}
    - Disclosure: {inline | link_only | omit | ask_user}
@@ -212,7 +232,10 @@ Prioritized actions based on findings above.
 
 ## Apply Contract
 
-- `oat-agent-instructions-apply` may only implement recommendations backed by evidence in this artifact.
+- `oat-agent-instructions-apply` may only implement recommendations backed by evidence in this artifact and its
+  companion bundle.
+- When the companion bundle exists, apply should treat `recommendations.yaml` plus `packs/*.md` as the primary
+  generation contract and use this markdown artifact as reviewer context.
 - Recommendations marked `omit` must stay out of generated instructions.
 - Recommendations marked `ask_user` require explicit user confirmation before generation.
 - If cited config/docs/files are missing at apply time, stop and re-run analyze or ask the user rather than inventing a replacement rule.

.agents/skills/oat-agent-instructions-analyze/references/bundle-summary-template.md

@@ -0,0 +1,31 @@
+---
+bundle_version: 1
+analysis_artifact: { artifact-path }
+manifest: recommendations.yaml
+pack_count: { N }
+generated_at: { YYYY-MM-DD }
+---
+
+# Agent Instructions Analysis Bundle Summary
+
+Companion bundle for `{artifact-path}`.
+
+## Purpose
+
+This bundle is the machine-oriented handoff for `oat-agent-instructions-apply`.
+The markdown analysis artifact remains the reviewer-facing summary. If they diverge, the bundle wins for generation.
+
+## Recommendation Index
+
+| ID        | Action          | Target   | Provider / Format   | Pack               | Notes             |
+| --------- | --------------- | -------- | ------------------- | ------------------ | ----------------- |
+| `rec-001` | {create/update} | `{path}` | {provider / format} | `packs/rec-001.md` | {short rationale} |
+| ...       |                 |          |                     |                    |                   |
+
+## Validation Rules
+
+- Every recommendation in `recommendations.yaml` must appear in this table.
+- Every listed pack file must exist under `packs/`.
+- Recommendation IDs must match across the markdown artifact, the manifest, and the pack filename.
+- Apply may use this summary for quick context, but it should load the manifest and matching pack before generating
+  output.

.agents/skills/oat-agent-instructions-analyze/references/recommendation-pack-template.md

@@ -0,0 +1,45 @@
+# Recommendation Pack: `rec-001`
+
+## Target
+
+- Action: {create / update}
+- Path: `{path}`
+- Provider / Format: {provider / format}
+- Disclosure: {inline / link_only / omit / ask_user}
+
+## Evidence
+
+- `{path}:{line}` - {why this evidence matters}
+- `{path}:{line}` - {supporting configuration, docs, or code pattern}
+
+## Structural Conventions
+
+- {imports, exports, file layout, frontmatter, or structural template rules}
+
+## Behavioral Conventions
+
+- {delegation, sequencing, runtime behavior, workflow rules, or architecture expectations}
+
+## Counter-Examples
+
+- {common mistake or anti-pattern}
+- {structurally valid but architecturally wrong output}
+
+## New-File Workflow
+
+1. {creation or wiring step}
+2. {registration, sync, or follow-up step}
+
+## Preferred Default for New Files
+
+{pattern A / pattern B / N/A}
+
+## Claim Corrections
+
+- `{old claim -> verified replacement}`
+
+## Generation Constraints
+
+- Must Include: {required claims, commands, references, examples, or behavior}
+- Must Not Include: {unsupported or stale guidance}
+- Link Targets: {path / URL or `N/A`}

.agents/skills/oat-agent-instructions-analyze/references/recommendations-manifest-template.yaml

@@ -0,0 +1,27 @@
+bundleVersion: 1
+analysisArtifact: { artifact-path }
+summary: summary.md
+recommendations:
+  - id: rec-001
+    action: create
+    target: path/to/file
+    provider: agents_md
+    format: AGENTS.md
+    severity: high
+    confidence: high
+    disclosure: inline
+    pack: packs/rec-001.md
+  - id: rec-002
+    action: update
+    target: path/to/existing-file
+    provider: cursor
+    format: glob-rule
+    severity: medium
+    confidence: medium
+    disclosure: link_only
+    pack: packs/rec-002.md
+
+# Rules:
+# - Every recommendation referenced here must also exist in the markdown analysis artifact.
+# - `pack` must be a relative path under this bundle directory.
+# - The manifest is the primary index used by oat-agent-instructions-apply when the bundle exists.

.agents/skills/oat-agent-instructions-apply/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-apply
-version: 1.4.0
+version: 1.6.1
 description: Run when you have an agent instructions analysis artifact and want to generate or update instruction files. Creates a branch, generates files from templates, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
@@ -50,7 +50,14 @@ Keep the question content consistent across hosts so the workflow remains portab
 
 ## Analyze vs Apply Boundary
 
-Treat the analysis artifact as the source of truth for what should be generated and why.
+Treat the analysis output as the source of truth for what should be generated and why.
+
+When a companion bundle exists beside the markdown artifact, the bundle is the primary generation contract:
+
+- `agent-instructions-<timestamp>.bundle/recommendations.yaml`
+- `agent-instructions-<timestamp>.bundle/packs/*.md`
+
+The markdown artifact remains the human-readable review summary.
 
 Apply may:
 
@@ -92,7 +99,26 @@ Search for the most recent analysis artifact:
 ls -t .oat/repo/analysis/agent-instructions-*.md 2>/dev/null | head -1
 ```
 
-**If found:** Read the artifact, extract findings and recommendations.
+If found, derive the companion bundle path:
+
+```bash
+BUNDLE_DIR="${ARTIFACT_PATH%.md}.bundle"
+MANIFEST_PATH="${BUNDLE_DIR}/recommendations.yaml"
+```
+
+**If found:** Read the artifact, then check for the companion bundle.
+
+**Bundle-first behavior:**
+
+- If `"$BUNDLE_DIR"` exists, validate `summary.md`, `recommendations.yaml`, and every referenced pack file.
+- Treat the bundle as the primary generation contract and the markdown artifact as review context.
+- If the bundle exists but is incomplete, stop and require a refreshed analysis rather than falling back silently to the
+  markdown artifact.
+
+**Legacy fallback:**
+
+- If no companion bundle exists, continue using the markdown artifact alone.
+- This keeps apply backward compatible with older analysis artifacts until the bundle contract is fully adopted.
 
 Validate that the artifact includes evidence, confidence, and progressive disclosure decisions for each recommendation.
 Also validate that every `link_only` recommendation includes at least one concrete link target to a canonical doc, config, or example.
@@ -101,6 +127,13 @@ If a recommendation updates or contradicts an existing rule, validate that it al
 If the artifact records a High/Medium glob-scoped opportunity with a recommended action to create, update, or split a
 rule, validate that a matching explicit recommendation exists. Apply should not infer missing rule work from the
 opportunities table.
+If the companion bundle exists, validate that:
+
+- every recommendation has a stable ID
+- every manifest entry points to an existing pack file
+- each pack preserves the executable fields apply relies on (`Evidence`, `Content Guidance`, `Must Include`,
+  `Must Not Include`, `Counter-Examples`, `New-File Workflow`, `Preferred Default for New Files`, `Claim Corrections`)
+
 If the artifact is missing that detail, treat it as incomplete:
 
 ```
@@ -134,8 +167,13 @@ For each recommendation in the analysis artifact, determine the action.
 Recommendations may originate from findings, provider baseline gaps, directory coverage gaps, or promoted glob-rule opportunities.
 The artifact should already specify the rationale, evidence, confidence, and disclosure decision.
 Do not rediscover conventions from scratch during this step.
+When the companion bundle exists, build the plan from the bundle manifest and recommendation packs first, then use the
+markdown artifact only to confirm reviewer-facing rationale and summary wording.
 Carry forward the artifact's structured handoff fields (`Content Guidance`, `Must Include`, `Must Not Include`,
-`Preferred Default for New Files`, `Claim Corrections`) into the plan wherever they are present.
+`Counter-Examples`, `New-File Workflow`, `Preferred Default for New Files`, `Claim Corrections`) into the plan wherever
+they are present.
+When the companion bundle exists, also carry forward the stable `Recommendation ID` and `Bundle Pack` path for each
+recommendation so plan review and generation stay aligned to the same pack file.
 
 **For provider baseline gaps (always-on provider files):**
 
@@ -254,10 +292,15 @@ If branch creation fails (e.g., uncommitted changes), ask the user to resolve an
 
 For each approved recommendation, in the order from Step 2:
 
+- When the companion bundle exists, load the approved recommendation's manifest entry and matching pack before
+  reading repo evidence or generating content.
+- Treat that pack as the executable contract for the recommendation. Do not generate from the markdown summary alone.
+
 **Creating new files:**
 
 1. Read the appropriate template from `references/instruction-file-templates/`.
 2. Read only the project context needed to fill the approved recommendation:
+   - the matching recommendation pack when the companion bundle exists
    - the evidence files cited in the artifact
    - `package.json` for commands and dependencies
    - directory structure for architecture section
@@ -284,7 +327,7 @@ For each approved recommendation, in the order from Step 2:
 
 **Updating existing files:**
 
-1. Read the existing file.
+1. Read the existing file and the matching recommendation pack when the companion bundle exists.
 2. Identify the section(s) that need updating based on the finding.
 3. Make targeted edits using only the approved recommendation and its cited evidence.
 4. Do not rewrite the entire file unless the user explicitly approves.

.agents/skills/oat-agent-instructions-apply/references/apply-plan-template.md

@@ -10,6 +10,7 @@ oat_providers: [{ providers }]
 
 **Date:** {YYYY-MM-DD}
 **Source Analysis:** `{analysis-artifact-path}`
+**Source Bundle:** `{bundle-path or legacy-markdown-only}`
 **Providers:** {agents_md, claude, cursor, ...}
 
 ## Instructions
@@ -36,10 +37,12 @@ If a recommendation lacks that detail, it should be blocked pending a fresh anal
 
 | Field                           | Value                                                                                                             |
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Recommendation ID               | `rec-001`                                                                                                         |
 | Action                          | {create / update}                                                                                                 |
 | Provider                        | {agents_md / claude / cursor / copilot}                                                                           |
 | Format                          | {AGENTS.md / Claude rule / Cursor rule / Copilot instruction / Copilot shim}                                      |
 | Target                          | `{target-file-path}`                                                                                              |
+| Bundle Pack                     | `{bundle-dir}/packs/rec-001.md` or `legacy-markdown-only`                                                         |
 | Rationale                       | {Why — references analysis finding #N or coverage gap #N}                                                         |
 | Evidence                        | {exact file refs / config / docs that justify the recommendation}                                                 |
 | Confidence                      | {high / medium / low}                                                                                             |