Merge pull request #5 from navapbc/jeffhorn/contribution-workflow-skills

Add contribution workflow docs and skills

Author: jeffhorn-nava

AGENTS.md

@@ -62,7 +62,8 @@ for a cross-project issue: `jeffhorn/oscer-42-short-description`.
 ### Pull requests
 
 Open all PRs as drafts; mark ready only after self-review. Use `.github/PULL_REQUEST_TEMPLATE.md`
-(GitHub pre-populates it).
+(GitHub pre-populates it). The `create-pr` skill guides naming, filling the template, review, and
+opening as a draft.
 
 ### Commits
 
@@ -72,8 +73,9 @@ Wire up the template once per clone: `git config commit.template .gitmessage`. S
 ### Drafting durable artifacts
 
 Before filing a durable, outward-facing artifact (issue, PR description, commit-message set), do not
-file the first draft: run the `review-draft` skill (checks quality, template adherence, voice,
-punctuation, house style, then revises), and file only after the caller or user approves the revision.
+file the first draft: run the `review-draft` skill, which checks quality, template adherence, voice,
+punctuation, house style, and formatting (no hard-wrapped issue or PR bodies, see `CONTRIBUTING.md`),
+then revises. File only after the caller or user approves the revision.
 
 ## Issue templates
 
@@ -91,6 +93,8 @@ Use the template that best fits the work; GitHub surfaces these on new-issue.
 For `technical-task.md`, fill "Starting point" and "Constraints and gotchas" thoroughly; those are
 what an agent or new developer needs to pick up work cold.
 
+The `create-issue` skill guides choosing the template, wording, labeling, reviewing, and filing.
+
 ## Architecture and CI
 
 Deep reference lives in path-scoped rule files that Claude Code auto-loads when you edit the relevant

CONTRIBUTING.md

@@ -1,5 +1,24 @@
 # Contributing
 
+## Contribution workflow
+
+The short version of how a change moves through this repo:
+
+1. **Start from an issue.** File one with the template that fits the work (epic, story, bug,
+   technical-task, spike, or chore). The `create-issue` skill walks you through choosing a template,
+   wording it for its audience, reviewing it, labeling it, and filing it.
+2. **Branch.** Use the naming shape in [Branching](#branching) below.
+3. **Make your changes.** Keep commits terse and explain why, not what. Wire up the commit template
+   (see [Commit message template](#commit-message-template)).
+4. **Review, then open a draft PR.** Run the `review-draft` skill on the PR description, then open
+   the PR as a draft and fill in the template (see [Opening pull requests](#opening-pull-requests)).
+   The `create-pr` skill walks you through branch naming, the review, and opening the PR.
+5. **Mark ready.** Move the PR out of draft once it is self-reviewed and CI passes.
+
+Run `review-draft` before any durable artifact goes up: an issue, a PR description, or a commit
+message set. It checks quality, template adherence, voice, punctuation, and house style. The rest of
+this document covers each step in detail.
+
 ## Local setup
 
 ### Python
@@ -40,6 +59,19 @@ jeffhorn/oscer-42-short-description
 
 Open all pull requests as drafts initially. Mark ready for review when the work is complete and self-reviewed.
 
+## Formatting issue and PR bodies
+
+GitHub renders issue descriptions, PR descriptions, and comments as GitHub-Flavored Markdown, and in
+that context it treats a single newline inside a paragraph as a line break (unlike a `.md` file
+rendered on github.com, where single newlines collapse into a space). So a body that was hard-wrapped
+at 72 or 80 columns renders as ragged, broken lines.
+
+Write one line per paragraph and let it soft-wrap. Separate paragraphs with a blank line. Lists,
+tables, and fenced code blocks keep their own line structure and are unaffected. This is the
+opposite of a commit message body, which is plain text and should wrap at 72 columns (see the
+commit template). The distinction is by artifact: wrap commit bodies, do not wrap issue or PR
+bodies.
+
 ## Running the pipeline
 
 ```bash

README.md

@@ -5,7 +5,7 @@ sources, producing a linked, agent-queryable knowledge base.
 
 ## How it works
 
-1. `sources.md` lists each source (`id`, `type`, `repo`, `ref`, optional `subpaths`) —
+1. `sources.md` lists each source (`id`, `type`, `repo`, `ref`, optional `subpaths`):
    the SDK, the Rails app template, SDK-consuming apps like OSCER, the `template-infra`
    infrastructure template, and the `platform-cli` (`nava-platform`) tool.
 2. The `generate-strata-docs` skill documents each source (one agent per source) using the
@@ -39,3 +39,9 @@ python -m scripts.lint_docs
 ```
 
 See `docs/superpowers/specs/2026-06-18-strata-documentation-engine-design.md` for the design.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow, branch naming, commit
+conventions, and the issue and PR templates. `AGENTS.md` is the canonical guide for both human
+contributors and AI agents.

skills/create-issue/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: create-issue
+description: Guides filing a new GitHub issue: picks the right template, writes it in the right register, applies the matching label, reviews the draft, and files it. Use when opening a new issue for this repo.
+---
+
+# Create Issue
+
+Walks from "I have something to file" to a filed issue that follows the repo's conventions. It picks
+the right template, helps write it in the right language for its audience, applies the matching
+label, runs a review pass, and files only after the draft is approved.
+
+## When to use
+
+Use whenever you are about to open an issue in this repo. It is especially helpful if you are not
+sure which template fits or how technical the wording should be.
+
+## Steps
+
+### 1. Choose the template
+
+Pick the template that matches the work. Templates live in `.github/ISSUE_TEMPLATE/`.
+
+| If the work is... | Use |
+|---|---|
+| A large initiative framed around an outcome, spanning several stories or tasks | `epic.md` |
+| A user-facing feature or improvement | `story.md` |
+| Something broken or behaving unexpectedly | `bug.md` |
+| An implementation handoff a developer or agent must pick up cold | `technical-task.md` |
+| A time-boxed investigation whose output is findings, not shipped code | `spike.md` |
+| Non-user-visible maintenance (dependency upgrades, CI, tooling) | `chore.md` |
+
+If two seem to fit, prefer the less technical one for anything a non-engineer might file (`story`
+over `technical-task`, `bug` over `technical-task`).
+
+### 2. Write in the right register
+
+- **Product templates** (`epic`, `story`): plain, outcome-oriented language. Describe user value and
+  what success looks like, not the implementation.
+- **Defect and maintenance templates** (`bug`, `chore`): accessible language. For `bug`, include
+  reproduction steps and expected versus actual behavior; mark technical fields optional where they are.
+- **Investigation template** (`spike`): accessible language; state the question and the time box.
+- **Handoff template** (`technical-task`): technical and specific. Fill in the "Starting point" and
+  "Constraints and gotchas" thoroughly; these are what an agent or new developer needs to start cold.
+
+Fill in the template's sections. Do not leave a heading with an empty body unless the template says
+it is optional.
+
+Write the body one line per paragraph; do not hard-wrap it. See "Formatting issue and PR bodies" in
+`CONTRIBUTING.md` for why.
+
+### 3. Apply the matching label
+
+Each template declares its label (`epic`, `story`, `bug`, `technical-task`, `spike`, `chore`). Apply
+that label when filing. If the label does not exist yet, create it first.
+
+### 4. Review the draft
+
+Run the `review-draft` skill on the issue body before filing. It checks quality, template adherence,
+voice, punctuation (no em dashes), formatting (no hard-wrapped body), and house style. Apply the
+findings you agree with.
+
+### 5. File
+
+Present the final draft for approval, then file it. Pass the body via a file so multi-line markdown
+survives the shell:
+
+```bash
+gh issue create --repo navapbc/strata-documentation-engine \
+  --title "<title>" --label <label> --body-file <path-to-body.md>
+```
+
+Issue titles are plain and imperative, with no bracket prefix (the label carries the type).

skills/create-pr/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: create-pr
+description: Guides opening a pull request: names the branch correctly, fills the PR template, reviews the description, and opens it as a draft. Use when opening a PR for this repo.
+---
+
+# Create PR
+
+Walks from a set of committed changes to an opened pull request that follows the repo's conventions.
+It checks the branch name, fills the PR template, runs a review pass on the description, and opens
+the PR as a draft.
+
+## When to use
+
+Use when your work is committed and ready to go up for review, or when you want a work-in-progress
+PR open early.
+
+## Steps
+
+### 1. Name the branch
+
+Use the team's branch shape:
+
+```
+<github-username>/<issue-number>-<short-kebab-description>
+```
+
+Skip the repo-name prefix when the branch lives in the same repo as the work. Include the
+originating project name only when a branch in this repo addresses an issue from a different project
+(for example `jeffhorn/oscer-42-short-description`). If the current branch does not follow this
+shape and has not been pushed yet, rename it with `git branch -m`.
+
+### 2. Decide the base
+
+- Most PRs target `main`.
+- If this work builds on another open PR's branch, target that branch instead (a stacked PR) and say
+  so in the PR's "Notes for reviewers" so the merge order is clear.
+
+### 3. Fill the PR template
+
+Use `.github/PULL_REQUEST_TEMPLATE.md`. Keep it terse and technical, in complete sentences: what
+changed and why, how (if not obvious from the diff), a checkable test plan, and notes for reviewers.
+Reference the issue with `Closes #n` or `Relates to #n`.
+
+Write the description one line per paragraph; do not hard-wrap it. See "Formatting issue and PR
+bodies" in `CONTRIBUTING.md` for why.
+
+### 4. Review the description
+
+Run the `review-draft` skill on the PR description before opening it. Apply the findings you agree
+with.
+
+### 5. Open as a draft
+
+Open the PR as a draft; this is the repo default. Pass the body via a file so multi-line markdown
+survives the shell:
+
+```bash
+git push -u origin <branch>
+gh pr create --draft --repo navapbc/strata-documentation-engine \
+  --base <base> --title "<title>" --body-file <path-to-body.md>
+```
+
+Mark the PR ready for review only after self-review is complete and CI passes.

skills/review-draft/SKILL.md

@@ -30,7 +30,10 @@ Review the draft along these five dimensions. Each is a separate lens; do not co
    For commits, the `.gitmessage` scaffold (imperative subject 50 chars or less, body explains why).
 3. **Voice.** Warm but professional, plain language where the audience is mixed, concise by cutting
    filler rather than clipping into fragments, complete sentences, "we" for shared decisions.
-4. **Punctuation.** No em dashes (hard rule). En dashes only for genuine numeric ranges.
+4. **Punctuation and formatting.** No em dashes (hard rule). En dashes only for genuine numeric
+   ranges. Line wrapping is by artifact: issue and PR bodies must not be hard-wrapped (one line per
+   paragraph); a commit message body should wrap at 72 columns. See "Formatting issue and PR bodies"
+   in `CONTRIBUTING.md`.
 5. **House style and stated preferences.** Anything the repo's conventions or the requester has
    asked for.
 
@@ -50,6 +53,8 @@ Each reviewer must:
 - report findings as a list, each with a location/quote, the issue, a concrete suggested fix, and a
   severity (BLOCKER / MAJOR / MINOR / NIT);
 - run a literal em-dash check and report every hit;
+- for an issue or PR body, check for hard-wrapped paragraphs (a paragraph broken across several
+  short lines) and report each;
 - end with a one-paragraph verdict.
 
 ### 3. Adjudicate
@@ -68,4 +73,6 @@ you rejected and the reason. Do not file the artifact; that is the caller's step
 
 - Keep reviewers cheap and the adjudication in a more capable model.
 - An em dash anywhere is at least a MAJOR finding and must be fixed before filing.
+- A hard-wrapped issue or PR body is at least a MAJOR finding: it renders as broken lines on GitHub.
+  Reflow each paragraph to a single line before filing.
 - This skill complements the "Drafting durable artifacts" convention in `AGENTS.md`.