product-card
Principal PM-posture skill that writes what a product turned out to be, once its foundation has settled — the project card's architecture-determined fields (Languages:, Language roots:, Test command:)
SKILL.mdskills/interactive-product/.claude/skills/product-card/SKILL.md
GitHubproduct-card
Purpose
Write the two things a settled product still has not said about itself: the project card's
architecture-determined fields, and the product's README.md. Both are derived from the
document set the definition chain and the foundation step have already settled; neither carries a
judgment those documents did not make.
This file is the orchestrator: posture, path resolution, the two repositories, the gates and the
commit. How to derive — which documents win where they disagree, how each card field is read out
of the architecture, what a settled product's README may claim, and what to do with a field the
documents do not determine — is the authoring prompt
prompts/rich.md, applied at Step 3. Nothing in it is restated
here.
It runs after the foundation step and before the skeleton. The order is not a preference:
<CORE>/launchers/product-skeleton/launcher.sh reads Languages: at :307 and Language roots: at
:448, both off the card this skill writes, so a skeleton run that precedes it places every frame at
the product root. Running the skeleton is not this skill's — see § Critical rules.
Posture
Principal PM role required. If invoked outside Principal PM posture (neither a principal-pm:
session nor the principal-pm subagent), stop and say: "product-card requires Principal PM
posture. Switch? (Open a session with the principal-pm: prefix, or run the principal-pm
subagent.)" Do not shed the role. Where the Principal PM ends and the delivery-tier PM
begins is the Principal PM loader stack's to say; take the boundary from there.
The two files, and the two repositories
| File | What this skill writes in it |
|---|---|
system/projects/<name>/project.md |
Languages:, Language roots:, Test command: — and nothing else on the card, comments included. A field the card lacks arrives as a whole line, its comment copied from the template. |
<Product path>/README.md |
the product's front door, corrected against the settled set. Created if absent. |
These two can sit in different repositories, and usually do. The card is in the instance repo — the directory this session opened in. The README is in whatever repo holds the product. Resolve both:
<instance-repo>— the session's own repo root. Everysystem/…and.claude/…path in this file resolves from it, and no stepcds away from it.<product-repo>— for a relativeProduct path:, this is<instance-repo>and the product is inside it. For an absolute one,git -C "<Product path>" rev-parse --show-toplevel, because a product with its own repo need not sit at that repo's root.
When the two are the same path, this run makes one commit. When they differ, it makes two — one per repo, each staging only its own file. A commit cannot span repositories, and the alternative to two commits is leaving one of the two files uncommitted, which is the state this skill exists to end.
Inputs and where they resolve
system/projects/<name>/project.md— the card, and the binding. ItsProduct path:field resolves the product; every laterProduct path:in this file means that field. A placeholder or an unfilled value halts the run: both outputs resolve from it, and there is nowhere to write even a report of the gap.- The foundation set —
<Product path>/docs/SDD.md,<Product path>/docs/adr/,<Product path>/docs/fdr.md,<Product path>/docs/nfdr.md. All four must exist: if any is missing at its resolved path, halt and name which. This skill writes down what the architecture decided, and the foundation step is where it was decided; run before it lands, the derivation has nothing to read and the card would carry a guess. - The rest of
<Product path>/docs/— read it by listing the directory, not by recalling filenames. Whatever else is there is input the run is entitled to. Skip binary assets. system/projects/<name>/agari.md— the declared terminus. It bounds what the README may promise. Absent or still the stamped placeholder: record it in the report and derive best-effort; never halt.<CORE>/templates/project_template.md— the grammar of every card field, in that field's own inline comment.
Workflow
Step 1 — Identify the project, resolve the paths
The argument is a project name, and nothing else. Given a path, a product name, or a card, halt
and say what was wanted: the name of a directory under system/projects/. Identity in, file derived —
a caller who may pass either form makes the run guess which one it holds, and a product name and a
project name coincide often enough that the guess is usually right and silently wrong the once it
matters.
Read system/projects/<name>/project.md. Resolve Product path:, <instance-repo> and
<product-repo> per § The two files, and the two repositories. If more than one project exists and
the target is ambiguous, halt and report the candidates — nothing resolves without a project.
Step 2 — Read current state, and check the inputs are on the record
Read every input named in § Inputs and where they resolve, in full, plus the README on disk if there is one.
The foundation set must be committed. Run
git -C "<product-repo>" status --porcelain -- <the four resolved paths>; any output halts the run,
naming the file, for the owner to commit or discard it before re-running. The card and the README
become the standing facts every later run reads, so a card derived from an uncommitted SDD can be
traced to text the owner later discards.
Note each input's Status: line as you read it. The report carries them (the prompt's § Inputs you
work from says why they are reported rather than written into either output).
Step 3 — Derive and write the two files
Apply the authoring prompt prompts/rich.md. It owns the
derivation entirely; this step adds only where the writing lands, which § The two files above
states.
Edit the card in place, field by field. Replace the value between **Label:** and the field's
inline comment, and leave the comment untouched — it is the field's grammar and the only statement of
what the field accepts. A field the settled set does not determine keeps the value it had.
A field the card does not carry at all is added, not skipped. A card stamped before the template
grew a field is missing its line entirely, so there is no value to replace — Language roots: is the
live case, and the frontmatter description's trigger list already names it. When the settled set determines such a
field, insert the whole line at the position <CORE>/templates/project_template.md gives it relative
to the fields the card does carry, and copy that template's inline comment for the field byte for
byte; never compose one, because the comment is the field's grammar and this skill is not its
author. When the settled set does not determine it, add nothing and say so in the report: the only
reader of Language roots: skips a value it finds empty
(<CORE>/launchers/product-skeleton/launcher.sh:449, if roots_raw:), so an absent line and a blank
one are the same line to it, and the blank one is a claim the run cannot make.
Step 4 — Commit through the builder
Commit through the shared builder — read <CORE>/doctrine/governance/commit_via_builder.md and supply
its variables. This step never hand-writes a git commit, spells a trailer, cds into a repo, or
stages by hand.
- The stage list.
--add system/projects/<name>/project.mdin<instance-repo>;--add <README path relative to <product-repo>>in<product-repo>. One--addper commit, and each commit stages only its own repo's file. - Two repos, two calls, with
--reponaming each in turn. Run the card's commit first: the README is the readable half and the card is the half a machine reads, and a run interrupted between the two leaves the machine-read half landed rather than the prose. - A run that changed neither file makes no commit. Report the state and stop.
- Actor:
--actor principal-pm --skill product-cardwhen running as theprincipal-pmagent; from an interactiveprincipal-pm:session with no agent named,--role "Principal PM" --skill product-card. - And
--prompt product-card/rich, naming the body this skill carries. - The directional is
Agari:orShukuba:, resolved against<CORE>/doctrine/governance/commit_format.md§ Directional trailer — the trailer follows the commit's scope. Both files are project-scoped, and this step runs upstream of the delivery loop, so a project with no open station resolves to its Agari. The same directional rides both commits: the product repo carries nosystem/projects/, and the builder reports that referent as uncheckable rather than wrong.
Step 5 — Report
Report, briefly:
- the card fields written, each with the value and the document it came from;
- the fields left alone, and why — unchanged by the settled set, or not determined by it;
- the README, by path, and which claims were corrected;
- the inputs read and the status each carried, every one of them, not only the unsettled;
- anything the documents did not determine, with what they would have to state for it to be derivable;
- the commit SHA per repo, or that the run changed nothing;
- the next move: the skeleton. Name
<CORE>/launchers/product-skeleton/launcher.sh <project>as the owner's, and say whether the product already has a skeleton. Do not run it.
Critical rules
- Two files, and no third. No code, nothing under
<Product path>/docs/, no other card field, no other project's card. - Never run the skeleton, and never place, move or delete a frame file. The launcher is deterministic and the owner runs it; this run only makes it correct to run.
- The card's stamp-time fields are not yours —
Product path:,Package slug:,Execution type:,Parallelism:— nor isSource material:, which is upstream of the PRD. - Every inline comment on the card survives byte for byte. A field the card carries is edited by replacing its value, never by rewriting its line; a field it lacks is added as a whole line, with the template's comment copied rather than composed.
- A document found wrong is a finding, not an edit. The definition and foundation documents belong to the seats that authored them; say so in the report and change nothing.
- There is no companion open-issues file, and its absence is a decision. What a run cannot derive reaches the owner in the report — the prompt's § When the documents do not determine a field owns why a card field is not the kind of thing a companion loop settles.