shipping-artifacts

Name: shipping-artifacts
Author: phuryn

725installs2.5kforks

How to install shipping-artifacts?

phuryn/pm-skills/shipping-artifacts

$npx -y skills add phuryn/pm-skills --skill shipping-artifacts

Installs into the current project.

Summary

The durable documentation set that makes an AI-built (vibe-coded) app reviewable before shipping. A small core every app needs — architecture, user/permission flows, permissions, variables/secrets, and a test-coverage map — plus conditional docs added only when they apply: emails

Files · 1

View on GitHub

SKILL.md

1	# Shipping Artifacts: The Docs That Make AI-Built Code Reviewable
2
3	## Purpose
4
5	AI agents write code fast, but they leave no durable record of intent — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.
6
7	These docs live in `documentation/` at the repo root and are written for two readers: a human reviewer and the next AI coding agent. They are the intended-state half of every later audit — a security or performance review is only as good as the intent it can compare the code against.
8
9	## How the set is organized
10
11	The set is not a fixed list — it is a small core plus conditional docs you add only when the capability exists.
12
13	- Core docs — every reviewable app has these surfaces, so always produce them.
14	- Conditional docs — include one only if the app actually has that capability. If it doesn't, write a single line in `architecture.md` ("No scheduled work — no `cron.md`.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
15	- Most docs are reverse-engineered from code by `/document-app`. The one exception is `tests.md`, which is derived from the other docs by `/derive-tests` — it is the verification map, not a description of a subsystem.
16
17	Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.
18
19	## Core documents
20
21	Each entry: file · one-line purpose · what it must capture · how a reviewer uses it.
22
23	1. `architecture.md` — what the system is and how it hangs together.
24	- Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short Known risks / assumptions list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
25	- Reviewer use: the root document — everything else is cross-referenced from here.
26
27	2. `flows.md` — the journeys where permissions and side effects are actually exercised.
28	- Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the authz check at each protected step (which claim/role/scope, on which resource, and the expected deny case); the trust-boundary crossings (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
29	- Reviewer use: the runtime view a static `permissions.md` matrix can't show — where and in what order authorization is enforced, and where it can be skipped.
30	- Anti-PRD rule: a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operational safety does not belong here. This is a security/operations map, not a feature spec.
31
32	3. `permissions.md` — who is allowed to do what.
33	- Must capture: roles/claims; where scope is derived (token vs. DB); a resource × operation × role matrix; which tables have row-level security and which rely on code-enforced checks.
34	- Reviewer use: the baseline an access-control audit compares the code against. `flows.md` shows it in motion; this is the static reference.
35
36	4. `variables.md` — configuration and secrets, mapped to risk.
37	- Must capture: a table of Name · used-by · scope (server/client) · source · rotation · risk; explicit confirmation that no secret is bundled client-side; a pre-go-live checklist.
38	- Reviewer use: the secrets/PII-leak surface and the rotation plan during incident response.
39
40	5. `tests.md` — the verification map: which documented rules are actually checked, which are only proposed, and which are checked by nothing.
41	- Must capture, in three clearly separated sections so the map can't read falsely green:
42	- Existing coverage — tests that are in the repo today, each tied to the rule it pins (so the map reflects reality, not a wish-l

People who liked this also viewed

6 picks

Type

shipping-artifacts

725installs2.5kforks

View on GitHub

How to install shipping-artifacts?

phuryn/pm-skills/shipping-artifacts

$npx -y skills add phuryn/pm-skills --skill shipping-artifacts

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Shipping Artifacts: The Docs That Make AI-Built Code Reviewable
2
3	## Purpose
4
5	AI agents write code fast, but they leave no durable record of intent — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.
6
7	These docs live in `documentation/` at the repo root and are written for two readers: a human reviewer and the next AI coding agent. They are the intended-state half of every later audit — a security or performance review is only as good as the intent it can compare the code against.
8
9	## How the set is organized
10
11	The set is not a fixed list — it is a small core plus conditional docs you add only when the capability exists.
12
13	- Core docs — every reviewable app has these surfaces, so always produce them.
14	- Conditional docs — include one only if the app actually has that capability. If it doesn't, write a single line in `architecture.md` ("No scheduled work — no `cron.md`.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
15	- Most docs are reverse-engineered from code by `/document-app`. The one exception is `tests.md`, which is derived from the other docs by `/derive-tests` — it is the verification map, not a description of a subsystem.
16
17	Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.
18
19	## Core documents
20
21	Each entry: file · one-line purpose · what it must capture · how a reviewer uses it.
22
23	1. `architecture.md` — what the system is and how it hangs together.
24	- Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short Known risks / assumptions list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
25	- Reviewer use: the root document — everything else is cross-referenced from here.
26
27	2. `flows.md` — the journeys where permissions and side effects are actually exercised.
28	- Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the authz check at each protected step (which claim/role/scope, on which resource, and the expected deny case); the trust-boundary crossings (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
29	- Reviewer use: the runtime view a static `permissions.md` matrix can't show — where and in what order authorization is enforced, and where it can be skipped.
30	- Anti-PRD rule: a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operational safety does not belong here. This is a security/operations map, not a feature spec.
31
32	3. `permissions.md` — who is allowed to do what.
33	- Must capture: roles/claims; where scope is derived (token vs. DB); a resource × operation × role matrix; which tables have row-level security and which rely on code-enforced checks.
34	- Reviewer use: the baseline an access-control audit compares the code against. `flows.md` shows it in motion; this is the static reference.
35
36	4. `variables.md` — configuration and secrets, mapped to risk.
37	- Must capture: a table of Name · used-by · scope (server/client) · source · rotation · risk; explicit confirmation that no secret is bundled client-side; a pre-go-live checklist.
38	- Reviewer use: the secrets/PII-leak surface and the rotation plan during incident response.
39
40	5. `tests.md` — the verification map: which documented rules are actually checked, which are only proposed, and which are checked by nothing.
41	- Must capture, in three clearly separated sections so the map can't read falsely green:
42	- Existing coverage — tests that are in the repo today, each tied to the rule it pins (so the map reflects reality, not a wish-l

People who liked this also viewed

6 picks

Type