78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
# 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`.
|