# 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/status.md`: current cross-repository progress and next work.
- `docs/decisions/`: durable rationale for significant architectural choices.
- `docs/plans/`: temporary implementation plans for substantial work.
- 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.
- Update `docs/status.md` when cross-repository work starts, becomes blocked,
  or is completed. Completed items must point to concrete evidence.
- Create a file in `docs/plans/` only for work spanning multiple meaningful
  steps or repositories. Remove or archive stale execution detail after the
  work is complete; durable rationale belongs in `docs/decisions/`.
- Use the status values `proposed`, `ready`, `in_progress`, `blocked`, `done`,
  and `deferred`.