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.

3.3 KiB Raw Blame History