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.

4.7 KiB Raw Blame History