Research: manifest format + grouping options #16

2026-05-24T21:13:15-04:00

didericis commented

2026-05-24 21:13:15 -04:00

Captures the two open questions surfaced by working through PRD 0011: should bottles and agents stay grouped in one manifest file or split per file (one MD per agent, one per bottle), and what format the manifest should take (JSON, YAML, MD with YAML frontmatter reusing Claude Code's subagent spec, or a new MD spec for both).

The doc walks both axes with pros/cons, shows a 2×4 matrix of combinations, and lands on a tentative recommendation: per-file MD with YAML frontmatter, with agent files shaped close enough to Claude Code's existing subagent spec that they can drop into ~/.claude/agents/ as a side effect, while bottles live in a dedicated directory under a claude-bottle-owned schema. The per-file shape is the bigger UX win — once that's in, the trust boundary expresses on disk as filesystem layout rather than resolver logic.

Explicitly flagged for the operator's decision: whether to take a PyYAML runtime dependency (the project's CLAUDE.md sets "low deps by default" as a guideline) vs hand-parsing a minimal frontmatter subset. Other open questions: Claude Code's tolerance for extra frontmatter fields, hidden .claude-bottle/ vs visible directory, migration tooling for existing JSON users.

Companion to PRD 0011, which solves the trust problem at the resolver layer. This research doc explores a structural alternative that would make the boundary self-documenting on disk — and supersede PRD 0011 if adopted.

Captures the two open questions surfaced by working through PRD 0011: should bottles and agents stay grouped in one manifest file or split per file (one MD per agent, one per bottle), and what format the manifest should take (JSON, YAML, MD with YAML frontmatter reusing Claude Code's subagent spec, or a new MD spec for both). The doc walks both axes with pros/cons, shows a 2×4 matrix of combinations, and lands on a tentative recommendation: per-file MD with YAML frontmatter, with agent files shaped close enough to Claude Code's existing subagent spec that they can drop into `~/.claude/agents/` as a side effect, while bottles live in a dedicated directory under a claude-bottle-owned schema. The per-file shape is the bigger UX win — once that's in, the trust boundary expresses on disk as filesystem layout rather than resolver logic. Explicitly flagged for the operator's decision: whether to take a PyYAML runtime dependency (the project's CLAUDE.md sets "low deps by default" as a guideline) vs hand-parsing a minimal frontmatter subset. Other open questions: Claude Code's tolerance for extra frontmatter fields, hidden `.claude-bottle/` vs visible directory, migration tooling for existing JSON users. Companion to PRD 0011, which solves the trust problem at the resolver layer. This research doc explores a structural alternative that would make the boundary self-documenting on disk — and supersede PRD 0011 if adopted.

didericis added 1 commit 2026-05-24 21:13:16 -04:00

docs(research): manifest format + grouping options

test / unit (pull_request) Successful in 12s

Details

test / integration (pull_request) Successful in 25s

Details

da969a503d

Captures the two open questions surfaced by PRD 0011: should bottles and agents stay grouped in one file or split per file, and should the format stay JSON or move to YAML / MD-with-frontmatter.

Recommends per-file MD-with-frontmatter (with agents shaped close to Claude Code's subagent spec so they can drop into ~/.claude/agents/ as a side effect), explicitly flags the PyYAML runtime dependency as a user-decision crossing the project's "low deps by default" line, and leaves several other choices (hidden dotdir vs visible, migration tooling) as open questions.

Companion to docs/prds/0011-cwd-manifest-trust-boundary.md (which solves the trust problem at the resolver layer); this doc explores a structural alternative that would make the boundary self-documenting on disk.

didericis referenced this pull request

2026-05-24 21:13:33 -04:00

PRD 0011: Trust boundary for cwd-supplied manifests #15

didericis commented

2026-05-24 21:29:10 -04:00

Merging — decision is option B × option 4: per-file MD-with-YAML-frontmatter for both agents and bottles, with a minimal hand-rolled frontmatter parser instead of pulling in PyYAML.

The minimal parser is viable because the YAML we'll accept is bounded: flat top-level keys mapping to strings, lists of strings, and one level of nested dicts for things like cred_proxy.routes entries. No anchors, no multi-line block scalars, no implicit type coercion, no flow-style mixing — a fraction of YAML's surface, a few hundred lines of parser at most. Keeps the project's stdlib-only / low-deps stance intact.

Follow-up PRD will spec the directory layout ($HOME/.claude-bottle/bottles/<name>.md, $HOME/.claude-bottle/agents/<name>.md, $CWD/.claude-bottle/agents/<name>.md), the exact frontmatter field names for the bottle schema, the agent-file shape (close to Claude Code's subagent format so the same file is reusable in ~/.claude/agents/, but not formally bound to it), and the migration story for existing JSON users. The trust boundary that PRD 0011 tried to enforce in code falls out for free under this layout — $CWD/.claude-bottle/ only has an agents/ subdir.

Merging — decision is **option B × option 4**: per-file MD-with-YAML-frontmatter for both agents and bottles, with a minimal hand-rolled frontmatter parser instead of pulling in PyYAML. The minimal parser is viable because the YAML we'll accept is bounded: flat top-level keys mapping to strings, lists of strings, and one level of nested dicts for things like `cred_proxy.routes` entries. No anchors, no multi-line block scalars, no implicit type coercion, no flow-style mixing — a fraction of YAML's surface, a few hundred lines of parser at most. Keeps the project's stdlib-only / low-deps stance intact. Follow-up PRD will spec the directory layout (`$HOME/.claude-bottle/bottles/<name>.md`, `$HOME/.claude-bottle/agents/<name>.md`, `$CWD/.claude-bottle/agents/<name>.md`), the exact frontmatter field names for the bottle schema, the agent-file shape (close to Claude Code's subagent format so the same file is reusable in `~/.claude/agents/`, but not formally bound to it), and the migration story for existing JSON users. The trust boundary that PRD 0011 tried to enforce in code falls out for free under this layout — `$CWD/.claude-bottle/` only has an `agents/` subdir.

didericis closed this pull request

2026-05-24 21:29:11 -04:00

didericis reopened this pull request

2026-05-24 21:31:16 -04:00

didericis merged commit b6046df5fb into main

2026-05-24 21:31:46 -04:00

didericis referenced this issue from a commit

2026-05-24 21:40:01 -04:00

docs: add PRD 0011 — per-file Markdown manifest

didericis referenced this pull request

2026-05-24 21:40:23 -04:00

PRD 0011: Per-file Markdown manifest #17