103 lines
4.8 KiB
Markdown
103 lines
4.8 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/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`.
|
|
- Prefer `ansible.builtin` modules where they directly fit the task.
|
|
`community.general` is an approved, stable dependency and its modules may be
|
|
selected freely when appropriate; declare and pin the collection wherever a
|
|
role or collection depends on it.
|
|
- 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`.
|