prometeu-studio/docs/packer/README.md

Packer Documentation

This directory contains the working, planning, and normative documentation for the packer domain.

packer is a standalone domain. It follows the same documentary cycle used elsewhere in the repository:

agendas -> decisions -> pull-requests -> specs -> learn

Tree

docs/packer/
├── agendas/
├── decisions/
├── learn/
├── pull-requests/
├── specs/
├── Prometeu Packer.md
└── README.md

Responsibilities

Prometeu Packer.md

Prometeu Packer.md is the current bootstrap specification for the domain.

Use it to:

• understand the current packer scope,
• recover the initial architecture and terminology,
• seed the split into smaller normative specs under specs/.

This document is useful as a draft source, but it should not become a permanent dumping ground for every future change.

agendas/

agendas/ contains open packer topics.

Use it to:

• frame unresolved problems,
• compare options and tradeoffs,
• define scope and non-goals,
• drive discussions toward a decision.

An agenda is a discussion artifact, not a final contract.

decisions/

decisions/ contains closed packer decision records.

Use it to:

• record the chosen direction,
• capture constraints and invariants,
• state what remains intentionally out of scope,
• identify which specs, plans, or code paths must be updated.

Decisions close debate. They are not brainstorming notes.

pull-requests/

pull-requests/ contains self-contained execution proposals.

Use it to:

• package a change for review,
• plan propagation across specs and implementation,
• define acceptance criteria,
• make tests and risks explicit before editing code or final specs.

specs/

specs/ contains the normative packer corpus.

Use it to:

• consolidate the official packer contract,
• split large draft material into stable chaptered specs,
• define behavior, constraints, interfaces, and conformance expectations.

Specs should only absorb already-closed decisions.

learn/

learn/ contains didactic consolidation.

Use it to:

• explain why the packer works the way it does,
• preserve hard-won operational knowledge,
• teach future contributors the model, pitfalls, and expected workflows,
• reorganize accumulated knowledge into a cleaner learning surface.

learn/ is not an archive of old decisions.

Recommended Flow

The preferred packer documentation flow is:

1. agendas/: open and shape the unresolved topic.
2. decisions/: close the architectural choice.
3. pull-requests/: plan how the decision will be propagated.
4. specs/: integrate the decision into normative text.
5. learn/: consolidate the final knowledge in a didactic form.

Practical Rule

• agendas/ stores open questions.
• decisions/ stores closed answers.
• pull-requests/ stores execution plans.
• specs/ stores the normative packer contract.
• learn/ stores teaching-oriented consolidation.

If implementation exposes a missing architectural choice, stop and return to agendas/ or decisions/.