# Project export: AgentQuilt

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: AgentQuilt turns complex AI agent prompts into modular, versioned building blocks - reducing merge conflicts, improving reviews, and making agent development easier to scale.
- Devpost: https://devpost.com/software/agentquilt
- GitHub: https://github.com/daxdue/agentquilt
- Demo: https://agentquilt.dev/
- Video: https://www.youtube.com/embed/ytxGxTxP4P4?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 3 GitHub contributor(s) — daxdue (42 commits), Claude Fable 5 (31 commits), github-actions[bot] (1 commits)

## Devpost submission (written by the team)

### Inspiration

Anyone who's maintained a shared agents, skills or AGENTS.md file knows the pain: it's one giant Markdown blob, and the moment two people touch it at the same time — one adding a testing rule, another adding a security rule — Git hands you a merge conflict in the middle of prose. Unlike code, agent instructions are semantic, not syntactic, so there's no clean three-way merge to fall back on. We also watched the multi-agent-platform problem compound this: teams now maintain near-duplicate instruction files for Codex, Cursor, Claude and Copilot by hand, each one drifting slightly from the others. We wanted structured source files to do for agent instructions what they already do for infrastructure and code: small, ordered, composable units that compile deterministically into whatever output each tool needs.

### What it does

AgentQuilt turns agent instructions into small Markdown fragments — one concern per file (role, build commands, testing rules, security rules) — stored under .agentquilt/agents/<agent-id>/ and numbered with gaps (010, 020, 030) so new fragments can be inserted without renumbering. A deterministic compiler reads the fragments plus a minimal agent.yaml manifest and produces identical, hash-verified Markdown every time — the same fragments compile straight to .codex/agents/*.toml, AGENTS.md, .claude/agents/*.md files, with no hand-written Codex config at all. agentquilt check is a gate that detects drift between source and disk, and a build-time tamper guard refuses to silently overwrite a generated file that's been hand-edited since the last build. On top of the CLI, we built a VS Code extension: a sidebar tree of agents and fragments read straight from the lock file, a live preview webview with real HTML rendering (via marked) instead of a raw escaped-string dump, a drift status bar that flips the moment a fragment changes and clears after a rebuild, and a one-click "Enable Provider" command that edits .agentquilt/config.yaml through the yaml package's Document API so comments and formatting survive.

### How we built it

The core is TypeScript with Zod schema validation and Commander for the CLI (agentquilt init, build, build --watch, check, agents add/list, skills add/list). The compiler normalizes fragments (LF line endings, trailing newlines) before hashing so the hash always matches the output, and orders fragments strictly by Unicode code point — never locale-aware sorting — to keep builds reproducible across machines. A Merkle-style target version binds fragment content, order, and format identity together, so any change to any of the three bumps the version. Adapters translate the same fragment set into platform-specific output: Claude, Codex (as standalone TOML, never touching .codex/config.toml), and the vendor-neutral Agent Skills format. For the demo, we scripted a live, unstaged comparison: a monolithic REVIEWER.md where two simultaneous branches collide in a merge conflict, versus the same two changes as separate fragment files, which merge cleanly and then compile into a combined Codex agent. The VS Code extension reads the same agentquilt.lock file the CLI writes, so the editor view and the CLI's idea of "current state" never disagree.

### Challenges we ran into

Model-tier resolution across platforms turned into a real trap, not just a demo bug: enabling Codex on the repository's own 14-agent dev portfolio broke the build outright, because modelTiers only mapped tier names like balanced to Claude model IDs, and Codex has no default model identifiers scaffolded (a deliberate choice per ADR-0015, not an oversight) — so every agent using model: balanced threw Tier "balanced" has no mapping for platform "codex". The fix wasn't to add Codex entries to fill the gap; it was recognizing that this particular target shouldn't have Codex enabled at all, and using a separate fixture repo to exercise Codex-specific features instead. Getting the Codex preview to render readably in the extension was its own fight — Codex's TOML output escapes newlines as literal \n in strings, so a naive text dump was unreadable; we ended up parsing it with smol-toml (the same library the CLI itself uses) to decode it back into real prose before rendering. And more mundanely: running concurrent work in the same checkout kept yanking uncommitted extension work across branches, which pushed us to build the extension in an isolated git worktree instead of fighting branch switches.

### Accomplishments we're proud of

Deterministic output is a genuinely hard guarantee to keep honest, and we kept it: the same fragments always hash to the same target version and always compile to byte-identical Markdown, verified in CI via agentquilt check. The tamper guard means the tool can refuse to overwrite a manually edited generated file instead of silently discarding someone's work — a small feature that prevents a real class of data loss. Getting a from-scratch VS Code extension to read live off the same lock file the CLI produces, with drift detection and auto-refreshing previews, gave the merge-conflict story a visual, editor-native payoff instead of just a terminal trick. And the "adopt an existing hand-written agent file with one command, then watch it start compiling to a second platform for free" flow is the kind of demo that makes the value concrete in under a minute.

### What we learned

The deepest lesson was that "platform-agnostic" is a much stricter constraint than it sounds: it means every named provider is an example instance of a registry entry, never a special case baked into the compiler, and it surfaces in unglamorous places like model-tier mappings, not just in adapter code. We also learned to treat generated files as sacred — agentquilt.lock, .codex/agents/*, AGENTS.md, CLAUDE.md are never hand-edited, full stop — because the moment you let one exception in, drift detection loses its meaning. On the tooling side, building the VS Code extension against the same lock file the CLI already writes (rather than re-deriving state) kept the two surfaces honest with each other for free, which we think is the right pattern for any companion UI layered on top of a CLI-first tool.

### What's next

Immediate: rehearsing and recording the VS Code extension demo, then committing the extension work out of its current worktree and getting it through review. Near-term, deferred items already on the roadmap: lint rules and semantic diffing for fragments, an eval runner for regression-testing agent behavior across compiled versions (not just prompt-presence checks), and release packaging/migration tooling. Longer-term, the "Enable Provider" and platform quick-pick UX in the extension point toward making platform onboarding a guided, zero-hand-editing flow rather than a config file edit — and there's an open question of whether AgentQuilt should ship a small library of common fragment patterns (security review blocks, testing conventions) that teams can pull in rather than write from scratch.

## README (from the GitHub repository)

# AgentQuilt

AgentQuilt is a Git-native framework for maintaining AI agent instructions as structured, composable, validated source files instead of manually edited Markdown prompts.

## Problem

Large agent Markdown files are hard to maintain in distributed teams. Multiple developers editing the same `.md` file often create merge conflicts, and those conflicts are difficult to resolve because agent instructions are semantic, not purely syntactic.

## Solution

AgentQuilt introduces a structured source model:

```
Agent = Manifest + Instruction Blocks + Generated Prompt
```

Developers edit small, ordered instruction blocks (fragments). AgentQuilt validates them and compiles them deterministically into platform-specific artifacts — the same sources can produce Claude Code agents, Codex custom agents, AgentSkills skills, Cursor rules, Copilot instructions, and more. Generated files are never hand-edited; a lock file records every fragment hash so CI can detect drift.

## Supported Platforms

| Platform | Type | Output |
|---|---|---|
| `claude` | adapter | `.claude/agents/<name>.md` (one file per agent) |
| `agentskills` | adapter | `.agents/skills/<name>/SKILL.md` (one skill per agent) |
| `codex` | adapter | `.codex/agents/<name>.toml` (one file per agent) |
| `cursor` | preset | `.cursor/rules/<agent>.mdc` (combined) |
| `copilot` | preset | `.github/copilot-instructions.md` (combined) |
| `gemini` | preset | `GEMINI.md` (combined) |

Plain Markdown document targets (e.g. a repo-level `AGENTS.md`) are also supported.

## Requirements

- Node.js >= 18

## Installation

```bash
npm install -g agentquilt
```

Or from source:

```bash
git clone https://github.com/daxdue/agentquilt.git
cd agentquilt
npm install
npm run build
```

## Get Started

```bash
# 1. Scaffold a project (in your repo root)
agentquilt init --platform claude
# Or emit standalone Codex custom-agent files
agentquilt init --platform codex
```

This creates `.agentquilt/config.yaml`, the `.agentquilt/agents/` source tree (plus `.agentquilt/skills/` when the `agentskills` platform is selected), and a `.gitattributes`. If you already have agents in `.claude/agents/` or skills in `.agents/skills/`, `init` adopts them as sources automatically. It refuses to overwrite an existing config unless you pass `--force`, and never overwrites an existing `.gitattributes`.

Adoption is limited to the platforms selected for that init run; bare `init`
selects Claude, while skills require `--platform agentskills`.

```bash
# 2. Add an agent
agentquilt agents add reviewer
```

This scaffolds `.agentquilt/agents/reviewer/` with a manifest and a first instruction block:

```
.agentquilt/agents/reviewer/
├── agent.yaml       # description, model tier, permissions
└── 010-role.md      # first instruction block
```

Edit `010-role.md`, and add more blocks as separate files — `020-style.md`, `030-testing.md`, … Blocks compile in filename order; use gaps of 10 so you can insert later without renumbering. Fragments in `.agentquilt/agents/_shared/` can be included across agents.

Codex targets inherit the model selected by Codex unless a model tier or override is configured. Existing Codex TOML files are not reverse-adopted; the first build preserves a differing file until `--force` explicitly lets AgentQuilt claim that output path.

Skills work the same way from their own source root: `agentquilt skills add <name>` scaffolds `.agentquilt/skills/<name>/` with a manifest and a `010-instructions.md`, compiled to `.agents/skills/<name>/SKILL.md` by an `agentskills` target.

```bash
# 3. Compile
agentquilt build
```

For a `codex` target, build writes standalone files under `.codex/agents/`; it never edits `.codex/config.toml`.

This writes the platform outputs (e.g. `.claude/agents/reviewer.md`) and `agentquilt.lock`. Commit sources and generated outputs together.

```bash
# 4. Guard it in CI
agentquilt check
```

`check` exits non-zero if any generated output or the lock is stale relative to the sources — so a PR that edits a generated file by hand, or edits sources without rebuilding, fails the gate.

**Exit codes:** `0` success · `1` drift detected by `check` or an output blocked by `build` ownership/tamper protection · `2` config or validation error · `3` I/O error.

## Commands

```bash
agentquilt init [--platform <p>...] [--force]   # Scaffold project; adopt existing agents
agentquilt build [--watch]                      # Compile all targets, write outputs and lock
agentquilt check                                # CI gate: detect drift between source and outputs
agentquilt agents add <name>                    # Scaffold a new agent directory
agentquilt agents list                          # List agents and resolved models per platform
agentquilt skills add <name>                    # Scaffold a new skill directory
agentquilt skills list                          # List skills and their descriptions
```

## Repository Structure

```
repo/
├── .agentquilt/               # All AgentQuilt sources live here
│   ├── config.yaml            # Project config (targets, model tiers, sourceDir)
│   └── agents/                # Flat source tree for project and lifecycle agents
│       ├── project/           # Fragments for the repository development guide
│       └── <development-agent>/
│           ├── agent.yaml     # Agent manifest
│           └── NNN-block.md   # Instruction blocks (ordered by prefix)
├── .claude/agents/            # Compiled Claude Code agent outputs (generated)
├── AGENTS.md                  # Compiled document target (generated)
├── agentquilt.lock            # Fragment hashes and target versions (generated)
├── packages/
│   ├── agentquilt-cli/        # CLI source (TypeScript, Commander, Zod)
│   └── website/               # agentquilt.dev landing page (Astro)
├── schemas/                   # JSON Schema definitions (language-neutral)
├── policies/                  # SDLC gate policies and risk register
├── scripts/                   # Utility scripts and spike tests
└── .docs/                     # Architecture specs, ADRs, SDLC/STLC docs
```

The config is discovered at `.agentquilt/config.yaml` (or `.agentquilt/config.json`);
the legacy root locations `agentquilt.config.yaml` / `agentquilt.config.json` are
still honored as a fallback.

## Project Status

**Current development line** — the core author → build → check workflow: deterministic compiler, Zod-validated schemas, Claude, Codex, and AgentSkills adapters, platform presets, lock file, and drift checking.

Planned next (see [Roadmap](.docs/roadmap.md)): eval-based regression testing, lint rules and semantic diff, and additional platform adapters.

## Goals

- Reduce merge conflicts in agent files
- Make agent changes reviewable
- Validate agent definitions before compilation
- Generate deterministic Markdown prompts
- Support CI gates
- Support eval-based regression testing (planned)
- Provide traceability for agent behavior changes

## Non-Goals

- Replacing human review
- Fully automatic semantic conflict resolution
- Building a web platform in the MVP
- Requiring live LLM calls for core compilation

## Documentation

- [Architecture Overview](.docs/architecture/overview.md)
- [v1 Specification](.docs/agentquilt-v1-spec.md)
- [v1.1 Addendum](.docs/agentquilt-v1.1-addendum.md)
- [ADR-0015: Codex Provider Adapter](.docs/architecture/adr/ADR-0015-codex-provider-adapter.md)
- [Glossary](.docs/glossary.md)
- [Roadmap](.docs/roadmap.md)
- [Contributing](CONTRIBUTING.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, commit format, PR expectations, and ADR policy.

## License

MIT


## Detected evidence (automated analysis)

Indexed codebase: 300 recognized source files, 1662 KB.
- Tailwind CSS (technology) — detected in the code
- TypeScript (language) — detected in the code
- AI coding agent: Claude Code — evidence: config files committed to the repository; commit authorship or trailers
- AI coding agent: Codex — evidence: config files committed to the repository

## Codebase structure (from repository index)

### Files (120 of 362)

```
.agentquilt/agents/ambiguity-detector/010-role.md
.agentquilt/agents/ambiguity-detector/020-ambiguity-patterns-to-flag.md
.agentquilt/agents/ambiguity-detector/agent.yaml
.agentquilt/agents/architecture-reviewer/010-role.md
.agentquilt/agents/architecture-reviewer/020-review-workflow.md
.agentquilt/agents/architecture-reviewer/030-review-checklist.md
.agentquilt/agents/architecture-reviewer/agent.yaml
.agentquilt/agents/deterministic-output/010-role.md
.agentquilt/agents/deterministic-output/020-determinism-review-workflow.md
.agentquilt/agents/deterministic-output/agent.yaml
.agentquilt/agents/documentation-reviewer/010-role.md
.agentquilt/agents/documentation-reviewer/020-doc-review-workflow.md
.agentquilt/agents/documentation-reviewer/agent.yaml
.agentquilt/agents/eval-designer/010-role.md
.agentquilt/agents/eval-designer/020-eval-workflow.md
.agentquilt/agents/eval-designer/030-example-eval-case.md
.agentquilt/agents/eval-designer/040-example-baseline-interaction.md
.agentquilt/agents/eval-designer/050-semantic-shift-examples.md
.agentquilt/agents/eval-designer/agent.yaml
.agentquilt/agents/feature-implementer/010-role.md
.agentquilt/agents/feature-implementer/020-implementation-workflow.md
.agentquilt/agents/feature-implementer/agent.yaml
.agentquilt/agents/implementation-planner/010-role.md
.agentquilt/agents/implementation-planner/020-planning-workflow.md
.agentquilt/agents/implementation-planner/agent.yaml
.agentquilt/agents/project/010-overview.md
.agentquilt/agents/project/020-architecture.md
.agentquilt/agents/project/030-documentation.md
.agentquilt/agents/project/040-development-practices.md
.agentquilt/agents/project/050-commands.md
.agentquilt/agents/project/060-design-principles.md
.agentquilt/agents/project/070-schemas.md
.agentquilt/agents/project/080-status.md
.agentquilt/agents/project/090-implementation-notes.md
.agentquilt/agents/project/100-package-and-links.md
.agentquilt/agents/regression-reviewer/010-role.md
.agentquilt/agents/regression-reviewer/020-regression-workflow.md
.agentquilt/agents/regression-reviewer/agent.yaml
.agentquilt/agents/release-reviewer/010-role.md
.agentquilt/agents/release-reviewer/020-release-readiness-workflow.md
.agentquilt/agents/release-reviewer/agent.yaml
.agentquilt/agents/repository-analyst/010-role.md
.agentquilt/agents/repository-analyst/020-investigation-workflow.md
.agentquilt/agents/repository-analyst/agent.yaml
.agentquilt/agents/schema-design/010-role.md
.agentquilt/agents/schema-design/020-schema-change-review.md
.agentquilt/agents/schema-design/agent.yaml
.agentquilt/agents/security-review/010-role.md
.agentquilt/agents/security-review/020-threat-assessment.md
.agentquilt/agents/security-review/030-secret-patterns.md
.agentquilt/agents/security-review/agent.yaml
.agentquilt/agents/supply-chain-risk/010-role.md
.agentquilt/agents/supply-chain-risk/020-dependency-review.md
.agentquilt/agents/supply-chain-risk/agent.yaml
.agentquilt/agents/test-engineer/010-role.md
.agentquilt/agents/test-engineer/020-verification-workflow.md
.agentquilt/agents/test-engineer/agent.yaml
.agentquilt/config.yaml
.agents/skills/analyze-issue/agents/openai.yaml
.agents/skills/analyze-issue/SKILL.md
.agents/skills/fix-ci/agents/openai.yaml
.agents/skills/fix-ci/SKILL.md
.agents/skills/implement-task/agents/openai.yaml
.agents/skills/implement-task/SKILL.md
.agents/skills/plan-change/agents/openai.yaml
.agents/skills/plan-change/SKILL.md
.agents/skills/prepare-pr/agents/openai.yaml
.agents/skills/prepare-pr/SKILL.md
.agents/skills/release-readiness/agents/openai.yaml
.agents/skills/release-readiness/SKILL.md
.agents/skills/review-tree/agents/openai.yaml
.agents/skills/review-tree/SKILL.md
.agents/skills/standard-development/agents/openai.yaml
.agents/skills/standard-development/SKILL.md
.changeset/config.json
.changeset/README.md
.claude/agents/ambiguity-detector.md
.claude/agents/architecture-reviewer.md
.claude/agents/deterministic-output.md
.claude/agents/documentation-reviewer.md
.claude/agents/eval-designer.md
.claude/agents/feature-implementer.md
.claude/agents/implementation-planner.md
.claude/agents/regression-reviewer.md
.claude/agents/release-reviewer.md
.claude/agents/repository-analyst.md
.claude/agents/schema-design.md
.claude/agents/security-review.md
.claude/agents/supply-chain-risk.md
.claude/agents/test-engineer.md
.claude/commands/prepare-pr.md
.claude/commands/release-readiness.md
.claude/hooks/pretooluse-guard.sh
.claude/settings.json
.claude/skills/analyze-issue/SKILL.md
.claude/skills/develop-issue/SKILL.md
.claude/skills/fix-ci/SKILL.md
.claude/skills/implement-task/SKILL.md
.claude/skills/plan-change/SKILL.md
.claude/skills/review-tree/SKILL.md
.codex/agents/ambiguity-detector.toml
.codex/agents/architecture-reviewer.toml
.codex/agents/deterministic-output.toml
.codex/agents/documentation-reviewer.toml
.codex/agents/eval-designer.toml
.codex/agents/feature-implementer.toml
.codex/agents/implementation-planner.toml
.codex/agents/regression-reviewer.toml
.codex/agents/release-reviewer.toml
.codex/agents/repository-explorer.toml
.codex/agents/schema-design.toml
.codex/agents/security-review.toml
.codex/agents/supply-chain-risk.toml
.codex/agents/test-reviewer.toml
.codex/config.toml
.codex/hooks.json
.codex/hooks/pretooluse-guard.sh
.docs/agentic-sdlc/agent-portfolio.md
.docs/agentic-sdlc/claude-code-pipeline.md
.docs/agentic-sdlc/codex-pipeline.md
[242 more files omitted for size]
```

### Dependencies

- package.json: @changesets/changelog-github@^0.7.0, @changesets/cli@^2.31.0
- packages/agentquilt-cli/package.json: @types/node@^20.10.6, @typescript-eslint/eslint-plugin@^6.17.0, @typescript-eslint/parser@^6.17.0, @vitest/coverage-v8@^1.6.1, @vitest/ui@^1.1.1, commander@^11.1.0, eslint@^8.56.0, prettier@^3.1.1, smol-toml@1.7.0, typescript@^5.3.3, vitest@^1.1.1, yaml@^2.4.1, zod@^3.22.4
- packages/website/package.json: @astrojs/sitemap@^3.2.1, @astrojs/tailwind@^5.0.0, @fontsource-variable/geist@^5.2.9, @fontsource-variable/geist-mono@^5.2.8, @types/node@^20.0.0, @vercel/analytics@^2.0.1, astro@^4.0.0, tailwindcss@^3.3.0, typescript@^5.3.0

### Recent commits (newest first)

- Merge pull request #57 from daxdue/changeset-release/main
- Version Packages
- Merge pull request #56 from daxdue/feature/agentquilt-lint
- feat(cli): implement agentquilt lint
- Merge pull request #55 from daxdue/revert/codex-agent-definitions
- Revert "Merge pull request #54 from daxdue/feature/codex-agent-definitions"
- Merge pull request #54 from daxdue/feature/codex-agent-definitions
- feat(agents): add advisory agentquilt agents check-models command
- feat(codex): enable Codex output for all agent definitions
- Merge pull request #50 from daxdue/fix/npm-version-pin
- fix(ci): pin npm upgrade to the 11.x line in release job
- Merge pull request #49 from daxdue/fix/npm-trusted-publishing
- fix(ci): switch release publishing to npm Trusted Publishing (OIDC)
- Merge pull request #48 from daxdue/changeset-release/main
- Version Packages
- Merge pull request #47 from daxdue/fix/release-checks-build-order
- fix(ci): build the CLI before running tests in the release checks job
- Merge pull request #46 from daxdue/feature/codex-support
- fix(codex): address code-review findings on the codex-adapter branch
- feat(codex): add provider adapter support

## Key source files (fetched from GitHub, selected and truncated for size)

### CONTRIBUTING.md

```markdown
# Contributing to AgentQuilt

## Development Principles

1. Structured source files are the source of truth.
2. Generated Markdown files must not be manually edited.
3. All significant decisions must be documented as ADRs.
4. Every behavior-changing change must be testable.
5. AI assistance is allowed, but human review is required.

## Branch Naming

Use:

- `feature/<short-description>`
- `fix/<short-description>`
- `docs/<short-description>`
- `refactor/<short-description>`
- `agent/<agent-name>-<change>`

Examples:

- `feature/instruction-block-schema`
- `docs/add-architecture-overview`
- `agent/qa-coach-release-readiness`

## Commit Message Format

Recommended:

`<type>(<scope>): <summary>`

Examples:

- `docs(architecture): add project structure ADR`
- `feat(schema): define agent manifest format`
- `feat(cli): add compile command`
- `test(compiler): add golden-file test`

## Pull Request Expectations

Each PR should include:

- Clear summary
- Change type
- Risk level
- Validation performed
- Affected components
- Expected behavior change, if any

If your change is user-visible (bug fix, new feature, CLI behavior
change), also run `npx changeset add` and commit the resulting file under
`.changeset/`. This is what marks a change as release-worthy and drives
the automated version bump and CHANGELOG entry — see
[release-process.md](.docs/sdlc/release-process.md). Purely internal
changes (docs, tests, CI tuning) don't need one.

## Generated Files Policy

Generated files must not be manually edited. If generated output changes, regenerate it using the appropriate command once the CLI exists.

## ADR Policy

Create an ADR when a change affects:

- Architecture
- Source format
- Generated artifact policy
- CI gates
- Security model
- Eval strategy
- Release process
```

### SPIKE_RESULTS.md

```markdown
# Spike Results — Phase 0 Acceptance Gates

## Status: ✅ BOTH SPIKES PASS

Both one-day spikes from §10 of the v1 spec have passed successfully, validating the core design assumptions.

---

## Spike 1 — Hash Determinism Across OSes ✅

**Objective:** Validate that the same fragment file produces identical `sha256-<hex>` hashes on all platforms (macOS, Linux, Windows) with different line ending variants and BOM.

**Implementation:** `scripts/spike-hash.mjs` implements §3.1 normalization algorithm exactly:
1. UTF-8 decode, strip leading BOM
2. Strip YAML front-matter block
3. Replace `\r\n` and lone `\r` with `\n`
4. Trim trailing newlines, append exactly one `\n`
5. Preserve inline trailing whitespace (Markdown hard line-breaks)

**Test fixtures:** `scripts/fixtures/`
- `plain.md` — Unix LF line endings
- `crlf.md` — Windows CRLF line endings
- `bom-crlf.md` — UTF-8 BOM + CRLF

**Result:**
```
plain.md:   sha256-cd2313a9d7c02b133167f58f75a77f0c582052f8163fc344b675da1778516f90
crlf.md:    sha256-cd2313a9d7c02b133167f58f75a77f0c582052f8163fc344b675da1778516f90
bom-crlf.md: sha256-cd2313a9d7c02b133167f58f75a77f0c582052f8163fc344b675da1778516f90
```

**✅ PASS:** All three fixtures produce identical hash. The normalization algorithm ensures cross-platform determinism.

---

## Spike 2 — Concurrent-PR Auto-Merge ✅

**Objective:** Validate that two branches each adding a new fragment + editing different existing fragments merge without conflicts in source files, and a rebuild produces a clean lock.

**Test scenario:**
1. Created minimal agent structure: `agents/_shared/` (2 fragments) + `agents/backend/` (2 fragments)
2. Branch A: added `agents/backend/030-new-a.md` + edited `agents/_shared/010-tone.md`
3. Branch B: added `agents/backend/040-new-b.md` + edited `agents/_shared/020-safety.md`
4. Merged both branches into main with `--no-ff`

**Result:**
- **Fragment files:** Zero conflicts. All source fragments merge cleanly.
- **Generated files:** Conflicts in `AGENTS.md` and `agentquilt.lock` (expected, as they are derived).
- **Rebuild:** `scripts/spike-build.mjs` deterministically regenerated both files with correct versions.
- **Lock consistency:** All 6 fragments recorded correctly; target version reflects the merged state.

**Git history:**
```
d6fa58b spike2(merge): resolve generated file conflicts via rebuild
4ad32a3 Merge branch A
0196e09 spike2(branch-b): add backend fragment, edit safety
d0265fc spike2(branch-a): add backend fragment, edit tone
b7ee1ff build: initial generated targets
```

**✅ PASS:** Concurrent edits to different fragments produce zero conflicts in source. Generated file conflicts are automatically resolved by a deterministic rebuild. This validates the core value proposition: **distributed teams can edit in parallel without semantic merge conflicts.**

---

## Key Validations

1. **Normalization is deterministic** — The same content always normalizes identically regardless of line-ending variant or BOM.
2. **Hashing is stable
[truncated — 936 more characters]
```

### package.json

```
{
  "name": "agentquilt-workspace",
  "version": "0.0.0",
  "private": true,
  "description": "AgentQuilt monorepo — workspace root for the framework and related tools",
  "homepage": "https://agentquilt.dev",
  "bugs": {
    "url": "https://github.com/daxdue/agentquilt/issues"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/daxdue/agentquilt.git"
  },
  "license": "MIT",
  "author": "daxdue",
  "workspaces": [
    "packages/*"
  ],
  "engines": {
    "node": ">=18"
  },
  "scripts": {
    "build": "npm run build -w packages/agentquilt-cli",
    "test": "npm test -w packages/agentquilt-cli",
    "website:dev": "npm run dev -w packages/website",
    "website:build": "npm run build -w packages/website",
    "check:pipeline-agents": "node scripts/check-pipeline-agent-drift.mjs",
    "package:check": "node scripts/check-package-contents.mjs",
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "npm run build -w packages/agentquilt-cli && changeset publish"
  },
  "devDependencies": {
    "@changesets/changelog-github": "^0.7.0",
    "@changesets/cli": "^2.31.0"
  }
}

```

### packages/website/package.json

```
{
  "name": "agentquilt-website",
  "version": "0.1.1",
  "description": "AgentQuilt landing page",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
  "dependencies": {
    "@astrojs/sitemap": "^3.2.1",
    "@fontsource-variable/geist": "^5.2.9",
    "@fontsource-variable/geist-mono": "^5.2.8",
    "@vercel/analytics": "^2.0.1",
    "astro": "^4.0.0"
  },
  "devDependencies": {
    "@astrojs/tailwind": "^5.0.0",
    "@types/node": "^20.0.0",
    "tailwindcss": "^3.3.0",
    "typescript": "^5.3.0"
  }
}

```

### packages/agentquilt-cli/package.json

```
{
  "name": "agentquilt",
  "version": "0.3.0",
  "description": "CLI tool for AgentQuilt agent framework — compiles Markdown fragments into deployment-ready agent instructions with deterministic versioning",
  "type": "module",
  "license": "MIT",
  "author": "daxdue",
  "homepage": "https://agentquilt.dev",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/daxdue/agentquilt.git",
    "directory": "packages/agentquilt-cli"
  },
  "bugs": {
    "url": "https://github.com/daxdue/agentquilt/issues"
  },
  "keywords": [
    "ai-agents",
    "agent-instructions",
    "prompt-management",
    "claude",
    "agents-md",
    "llm",
    "markdown-compiler",
    "cli",
    "developer-tools",
    "agentic"
  ],
  "engines": {
    "node": ">=18"
  },
  "main": "dist/index.js",
  "bin": {
    "agentquilt": "dist/index.js"
  },
  "files": [
    "dist"
  ],
  "publishConfig": {
    "access": "public",
    "provenance": true
  },
  "scripts": {
    "build": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
    "dev": "tsc --watch",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:ui": "vitest --ui",
    "coverage": "vitest run --coverage",
    "lint": "eslint src --ext .ts",
    "format": "prettier --write src tests",
    "prepublishOnly": "npm run build && npm test"
  },
  "dependencies": {
    "commander": "^11.1.0",
    "smol-toml": "1.7.0",
    "yaml": "^2.4.1",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "@types/node": "^20.10.6",
    "@typescript-eslint/eslint-plugin": "^6.17.0",
    "@typescript-eslint/parser": "^6.17.0",
    "@vitest/coverage-v8": "^1.6.1",
    "@vitest/ui": "^1.1.1",
    "eslint": "^8.56.0",
    "prettier": "^3.1.1",
    "typescript": "^5.3.3",
    "vitest": "^1.1.1"
  }
}

```

### packages/agentquilt-cli/src/index.ts

```typescript
#!/usr/bin/env node

import { readFileSync } from "fs";
import { fileURLToPath } from "url";
import path from "path";
import { program } from "commander";
import { registerInitCommand } from "./commands/init.js";
import { registerBuildCommand } from "./commands/build.js";
import { registerCheckCommand } from "./commands/check.js";
import { registerLintCommand } from "./commands/lint.js";
import { registerAgentsCommand } from "./commands/agents/index.js";
import { registerSkillsCommand } from "./commands/skills/index.js";
import "./core/adapters/claude.js";
import "./core/adapters/agentskills.js";
import "./core/adapters/codex.js";

// Read from package.json at runtime rather than hardcoding, so --version
// can't drift from the published package version the way it silently did
// through 0.1.0/0.1.1 (dist/ and package.json are always siblings, both in
// this repo and in a real npm install).
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const packageJsonPath = path.join(__dirname, "..", "package.json");
const { version } = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
  version: string;
};

program
  .name("agentquilt")
  .description("Deterministic compiler for AI agent instruction files")
  .version(version);

registerInitCommand(program);
registerBuildCommand(program);
registerCheckCommand(program);
registerLintCommand(program);
registerAgentsCommand(program);
registerSkillsCommand(program);

program.parse(process.argv);

if (!process.argv.slice(2).length) {
  program.outputHelp();
}

```

### packages/agentquilt-cli/src/commands/agents/index.ts

```typescript
import { Command } from "commander";
import { registerAddAgentCommand } from "./add.js";
import { registerAgentsListCommand } from "./list.js";

export function registerAgentsCommand(program: Command): void {
  const agentsCmd = program.command("agents").description("Manage agent definitions");
  registerAddAgentCommand(agentsCmd);
  registerAgentsListCommand(agentsCmd);
}

```

### packages/agentquilt-cli/src/commands/skills/index.ts

```typescript
import { Command } from "commander";
import { registerAddSkillCommand } from "./add.js";
import { registerSkillsListCommand } from "./list.js";

export function registerSkillsCommand(program: Command): void {
  const skillsCmd = program.command("skills").description("Manage skill definitions");
  registerAddSkillCommand(skillsCmd);
  registerSkillsListCommand(skillsCmd);
}

```

### packages/agentquilt-cli/src/core/adapters/index.ts

```typescript
import type { CanonicalAgentRecord } from "../agentLoader.js";
import type { ResolvedModel } from "../modelResolver.js";
import type { AgentQuiltConfig } from "../../schemas/config.schema.js";

export interface AdapterOutput {
  path: string;     // repo-relative path for the output file
  content: string;  // full file content
  kind?: "file";     // default "file"; the only kind any adapter emits (ADR-0015 rejected managed-region injection)
}

export interface Adapter {
  readonly id: string;
  readonly ADAPTER_VERSION: string;
  outputsFor(
    record: CanonicalAgentRecord,
    resolvedModel: ResolvedModel,
    config: AgentQuiltConfig
  ): AdapterOutput[];
}

// Adapter registry
const ADAPTERS = new Map<string, Adapter>();

export function registerAdapter(adapter: Adapter): void {
  ADAPTERS.set(adapter.id, adapter);
}

export function getAdapter(id: string): Adapter | undefined {
  return ADAPTERS.get(id);
}

export function knownAdapters(): string[] {
  return Array.from(ADAPTERS.keys());
}

```

### .github/dependabot.yml

```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/packages/agentquilt-cli"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

```

[279 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]