Engineering docs
Portable equal-primary Claude and Codex agent harness for a governed agentic SDLC
npx -y skills add mblauberg/provenant --skill engineering-docsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 27 days oldThe repository was created 27 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use for creating, placing, indexing, updating, or archiving engineering docs and docs structures. Not for prose-only rewriting or session continuity; use engineering-writing or session.
SKILL.md
3.6 KB, as published. Nobody here has run it
Engineering docs
Treat docs as durable, audited deliverables. Cite decisions, archive retired
docs, use Australian English and load engineering-writing for substantial
prose.
Default homes
Resolve project instructions and existing canonical owners first. The table is a fallback only when project-write authority includes documentation setup. In advisory mode, propose paths without creating them.
| Type | Home | Convention |
|---|---|---|
| Stories / specs | docs/stories/ or docs/specs/ | NN-slug.md, indexed |
| Architecture map | docs/ARCHITECTURE.md | current state; links to ADRs |
| Diagrams | owning document or docs/diagrams/ | colocate by default; separate when independently owned, reused or generated |
| Runbooks | docs/runbooks/ | numbered steps and verification |
| Open-decision register | docs/OPEN_DECISIONS.md | one row per user/owner gate; never auto-answered |
| Threat models | docs/threat-models/ | STRIDE/LINDDUN structure |
| Rolling state | docs/STATE.md | rules embedded in the file (session skill) |
| Archive | docs/archive/ | indexed by its README |
Binding rules
- Verify a decision ID against its log before citing it.
- Regenerate generated files; never hand-edit them.
- Keep numbered directories contiguous and update their index in the same change.
- Quote and link frozen legal, compliance or gate wording; do not paraphrase.
- Anti-bloat: an agent-facing doc past ~15 KB is a split/merge review
signal, not an automatic split. Split when owners, audiences, lifecycles or
change rates differ; merge duplicate truths or tiny files always changed
together. Keep one canonical owner and make current claim → owner → evidence
reachable in at most three hops. Session residue never accumulates in live
dirs; use
session's context-hygiene pass.
Diagrams
Default to Mermaid in markdown for GitHub and operational docs. Use
flowchart for routing, sequenceDiagram for calls, stateDiagram-v2 for
lifecycles, erDiagram for schemas and a C4-style flowchart for context.
Place a load-bearing diagram in the document whose explanation it supports when both have the same audience, owner and lifecycle. Use a separate diagram file when it is reused, generated, or maintained as an independent artifact.
Render and visually inspect before commit. Parser success proves syntax, not layout quality:
src="$(pwd)/path/to/owning-document.md"
out="$(mktemp -d)"
(cd "$out" && mmdc -i "$src" -o check.md)
Keep one conceptual level per diagram. Split overview from detail when return
edges distort the main path. Check normal and narrow widths for overlap,
clipping, crossings, blank space and unreadable scaling. Apply
diagram-quality.md. Use d2-diagrams only
when fixed layout or publication quality justifies a rendered asset.
Retirement and archiving
Preserve durable records in the archive and update its index. After an authorised move, repair inbound links and remove a pointer-only file when repository history and the relevant index preserve provenance. Keep a tombstone only while a stable external link or unsupported consumer still requires one. Deleting a substantive record still requires owner authority.
Red flags
- Unverified decision citation.
- Hand-edited generated output.
- Deleted history or an unindexed new document.