# Engineering Docs

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-mblauberg-provenant-engineering-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mblauberg](https://agentstack.voostack.com/s/mblauberg)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mblauberg](https://github.com/mblauberg)
- **Source:** https://github.com/mblauberg/provenant/tree/main/skills/engineering-docs

## Install

```sh
agentstack add skill-mblauberg-provenant-engineering-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

1. Verify a decision ID against its log before citing it.
2. Regenerate generated files; never hand-edit them.
3. Keep numbered directories contiguous and update their index in the same
   change.
4. Quote and link frozen legal, compliance or gate wording; do not paraphrase.
5. **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:

```sh
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](references/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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mblauberg](https://github.com/mblauberg)
- **Source:** [mblauberg/provenant](https://github.com/mblauberg/provenant)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mblauberg-provenant-engineering-docs
- Seller: https://agentstack.voostack.com/s/mblauberg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.