Initial commit

AGENTS.md

@@ -0,0 +1,77 @@
+# 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`.