# Workspace Instructions

## Purpose

This is the control repository for the Ansible roles and collection that
deploy the D&D transcript-processing pipeline. It owns cross-repository plans,
decisions, status, and workspace tooling. Each application and Ansible project
is an independent Git repository.

## Repository Map

Repositories inside this directory:

- `ansible-collection-dnd`: the `rakestraw.dnd` collection that bundles and
  distributes the pipeline suite.
- `ansible-role-dnd-pipeline`: independent source repository for the
  suite-level role exposed by the collection as `rakestraw.dnd.pipeline`.
- `ansible-role-{narratio,notarius,audita,seriatim,scriptorium}`: standalone
  application roles.
- `rakestraw-ansible`: working deployment repository containing the
  `pipeline_dnd` proof of concept; treat it as read-only reference unless the
  task explicitly includes it.

Relevant upstream repositories are siblings of this directory:

- `../{narratio,notarius,audita,seriatim,scriptorium}`: application source and
  authoritative application contracts.
- `../narratio-prompts`: pipeline prompt-library content.

Use `workspace.yml` as the complete machine-readable inventory of paths and
remotes.

## Sources of Truth

- `docs/roadmap/mvp.md`: settled MVP scope, architecture, and open design work.
- `docs/roadmap/features/`: durable scope and target state for selected units
  of work.
- `docs/status.md`: current cross-repository progress and next work.
- `docs/decisions/`: durable rationale for significant architectural choices.
- `docs/roadmap/implementation.md`: the single active staged implementation
  plan, replaced for each selected feature after its feature roadmap is agreed.
- Application repositories: CLI, configuration, build, and integration
  contracts.
- Individual Ansible repositories: implementation and repository-local tests.

Do not duplicate an application contract in workspace documentation when a
link and a concise deployment consequence are sufficient.

## Working Conventions

- Confirm the target repository before editing; never treat this directory as
  a monorepo.
- Inspect the relevant upstream application before designing or changing its
  Ansible role.
- Keep standalone application roles independently usable. Cross-application
  policy belongs in `ansible-role-dnd-pipeline` and is exposed to consumers as
  `rakestraw.dnd.pipeline`.
- Use `ansible.builtin` modules directly unless a concrete requirement justifies
  another dependency.
- Prefer codebase-memory graph tools for code discovery. Use text/file search
  for documentation, configuration, literals, or when the graph is
  insufficient.
- Preserve unrelated and pre-existing working-tree changes in every
  repository.
- Never place credentials or secret values in plans, examples, inventory, or
  tests.
- Validate changes in the repository that owns them and report the commands
  run.

## Planning and Progress

- Update `docs/roadmap/mvp.md` when a design question becomes a settled scope
  or architecture decision.
- Discuss and select the next unit of work before planning implementation.
- Give each selected feature a four-digit identifier and a durable document at
  `docs/roadmap/features/<id>-<slug>.md`. Add the same identifier to
  `docs/status.md`.
- Write and agree on the feature roadmap before writing its implementation
  plan. The roadmap owns scope, target end state, rationale, constraints, and
  acceptance criteria.
- Always write the current implementation plan to
  `docs/roadmap/implementation.md`. Replace that file when planning the next
  selected feature; Git history preserves prior plans when needed.
- Write implementation plans as dependency-ordered stages suitable for
  GPT-5.6-Terra to execute sequentially. Number stages with consecutive
  integers beginning with `Stage 1`; do not skip numbers or use nested stage
  numbering. Each stage must identify its repository, preconditions, required
  behavior, validation, completion criteria, and expected commit.
- Resolve architectural choices during roadmap and plan review. Do not leave
  unresolved design judgment to the implementation agent.
- Update `docs/status.md` when cross-repository work starts, becomes blocked,
  or is completed. Completed items must point to concrete evidence.
- Out-of-band implementation should commit each completed stage when that
  stage leaves its owning repository valid. Review the implementation and its
  validation evidence before marking the feature complete.
- Retain feature roadmaps as durable records. Remove or archive obsolete
  implementation detail after completion; durable architectural rationale
  belongs in `docs/decisions/`.
- Use the status values `proposed`, `ready`, `in_progress`, `blocked`, `done`,
  and `deferred`.