Skill: joshp123/pr-commit-workflow (version 1.0.0)

--- name: pr-commit-workflow description: This skill should be used when creating commits or pull requests, enforcing a human-written PR structure, intent capture, and evidence in agentic workflows. --- # PR + Commit Workflow ## Overview Enforce a high-signal commit workflow and a human-written PR format. Keep global process rules as source of truth and make PRs reviewable by humans and agents. ## Workflow Decision Tree - If the task is about commits only, follow `references/workflow-commit.md`. - If the task involves PR creation or PR updates, follow `references/workflow-pr.md`. ## Global Rules - If the repo has `AGENTS.md` or `docs/agents/PROCESS.md`, read it for repo-specific rules. - Require user-supplied, human-written intent for every PR. Never generate or paraphrase this text. - Use `/tmp` for PR body drafts and `gh pr edit --body-file` for updates. ## Commit Workflow (entry point) - Execute the steps in `references/workflow-commit.md`. - Use the message format in `references/commit-format.md`. ## PR Workflow (entry point) - Execute the steps in `references/workflow-pr.md`. - Use the template in `references/pr-human-template.md` verbatim. - Use `scripts/build_pr_body.sh` to gather environment metadata if available. ## Resources - `references/workflow-commit.md`: commit checklist and evidence expectations. - `references/workflow-pr.md`: PR creation/update flow, comment checks, and evidence rules. - `references/pr-human-template.md`: human-written PR structure (must be used as-is). - `references/commit-format.md`: commit message format and examples. - `scripts/build_pr_body.sh`: environment metadata collector for PR prompt history section.

path: references/workflow-pr.md
content: # PR Workflow

## Preconditions
- If the repo has `AGENTS.md` or `docs/agents/PROCESS.md`, read it for repo-specific rules.

## Mandatory Human Intent Capture
- Prompt the user for a human-written intent section.
- Do not draft, rewrite, summarize, or paraphrase the intent.
- Paste the intent verbatim at the very top of the PR body under the heading `Human written summary:`.
- Use the lead-in line `The intent of this change is, as written by a human:` and put the intent in a blockquote.
- Add a single italicized attribution line after the blockquote (blank line between quote and italics). Use the exact format in `pr-human-template.md`.
- Do not include instruction text (e.g., "paste verbatim") in the PR body.
- If intent is missing, stop and request it.

## Steps
- Ensure branch is clean and only includes the intended commits.
- Check for other open PRs that may conflict.
- Ask the user whether to request reviewers; only request collaborators.
- Build PR body using `references/pr-human-template.md`.
- Fill non-human sections with factual, testable info.
- Use `/tmp` + `gh pr edit --body-file` for updates.
- Create PR with `gh pr create` if not already open.
- Default PRs to draft until tests + review pass; ask user before marking ready.

## Prompt History Requirements
- Include ISO-8601 timestamps with timezone.
- Prefer agent history search tools (`cm`/`cass`, Codex logs, etc.); if unavailable, fall back to manual logs and note the fallback.
- Include the full prompt history verbatim; do not omit prompts.
- If a prompt contains sensitive info, redact only the sensitive portion and keep the entry.
- Always include Environment metadata under Prompt History:
  - Harness
  - Model
  - Thinking level
  - Terminal
  - System
- Use `scripts/build_pr_body.sh` to collect environment fields when possible.
- If any field is unknown, ask the user to fill it.
- Format prompt history as a table: `ISO-8601` | `prompt` and wrap prompts in inline code (use double backticks if the prompt contains backticks).
- For very long prompts (>200 chars), consider using heading+codeblock format instead of table rows to avoid rendering issues.

## Review Comment Checks
- Always check both:
  - `gh pr view <id> --comments`
  - `gh api /repos/<org>/<repo>/pulls/<id>/comments --paginate`
- Summarize inline feedback with file + line + fix status.


path: references/workflow-commit.md
content: # Commit Workflow

## Preconditions
- If the repo has `AGENTS.md` or `docs/agents/PROCESS.md`, read it for repo-specific rules.

## Steps
- Ensure one logical change per commit; avoid unrelated files.
- Stage surgically; never use `git add .` or sweeping adds.
- Use surgical commits only; partials ok, bulk commits not ok.
- Amend HEAD for feedback on the same logical change; new commit only for distinct changes.
- Run the full test suite (or repo gate) before committing.
- Capture evidence of tests (command + outcome).
- Write the commit message using `references/commit-format.md`.
- If a repo has a committer script, use it.

## Evidence Recording
- Record the exact command and outcome for:
  - Smoke test (mandatory when feature behavior changes).
  - Full suite or gate (lint/typecheck/tests/docs).
- If blocked, state why and what is missing.


path: references/commit-format.md
content: # Commit Message Format

## Requirements
- Prefix with 🤖.
- Use multi-line message: subject + what/why + tests.
- Prefer heredoc over `-m` to avoid quoting errors.

## Template
Subject line:
- `🤖 <type>: <short summary>`

Body:
- `What: <bullet list>`
- `Why: <bullet list>`
- `Tests: <command + result>`

## Example (heredoc)
```
git commit -F - <<'MSG'
🤖 docs: clarify PR workflow expectations

What:
- add explicit human-written intent requirement
- split commit/PR sections in workflow skill

Why:
- enforce reviewer context and transparency
- reduce PR churn from auto-generated summaries

Tests:
- not run (docs-only)
MSG
```

## Multi-Model Attribution
If multiple models contributed, add Co-Authored-By trailers:
```
Co-Authored-By: GPT-5.2-Codex <[REDACTED_SECRET]>
Co-Authored-By: Gemini Pro <[REDACTED_SECRET]>
```


path: references/pr-human-template.md
content: # Human written summary:
The intent of this change is, as written by a human:
> <USER_TEXT_HERE>

_The rest of this PR was written by <MODEL>-<THINKING_LEVEL>, running in the <HARNESS> harness. Full environment + prompt history appear at the end._

# Changes
- <bullet>

# Tests
- <command + result>

# Risks
- <bullet or "None: <reason>">

# Follow-ups
- <bullet or "None">

# Prompt History

## Environment
Harness: <value>
Model: <value>
Thinking level: <value>
Terminal: <value>
System: <value>

## Prompts
| ISO-8601 | Prompt |
| --- | --- |
| <timestamp> | `<prompt text>` |


path: README.md
content: # pr-workflow-skill

A skill for high-signal PR and commit workflows in agentic AI coding. Works with your coding agent of choice.

## What it does

- Enforces **human-written intent** at the top of every PR (never AI-generated)
- Captures **full prompt history** with timestamps for auditability
- Records **environment metadata** (harness, model, thinking level, terminal, system)
- Guides **surgical commits** (one logical change per commit, no bulk adds)
- Defaults PRs to **draft until tests + review pass**

## Installation

Give this to your coding agent:

> Install the PR workflow skill from https://github.com/joshp123/pr-workflow-skill — clone it to wherever I keep skills, and wire it up so it activates when I create commits or PRs.

## Usage

The skill activates when creating commits or PRs. It will:

1. **Prompt you for intent** — your own words explaining WHY this change exists
2. **Build the PR body** using the template in `references/pr-human-template.md`
3. **Collect environment metadata** using `scripts/build_pr_body.sh`
4. **Include full prompt history** in table format

## Example PR

---

### Human written summary:
The intent of this change is, as written by a human:
> I want to make a global skill to encode my PR workflow. the skill should help me (a lazy idiot) make good PRs using my coding agents, explaining what i've done, so that maintainers get high quality contributiions, without noise, espeically including rpompt histories.

_The rest of this PR was written by gpt-5.2-codex-high, running in the codex harness. Full environment + prompt history appear at the end._

### Changes
- New skill: `skills/pr-commit-workflow/` — global PR/commit workflow with hard human-intent gate and explicit prompt-history requirements
- Human-written PR template: verbatim intent at top (blockquote), model attribution, full prompt history at bottom
- Reviewer-prompting + default-draft policy: PRs stay draft until tests + review pass
- Environment metadata collector script: detects harness/model/thinking/terminal/system programmatically
- Surgical commit guidance: one logical change per commit, no bulk `git add`

### Tests
- `nix flake check` — ok (warnings: uncommitted tree, unknown flake output `homeManagerModules`)

### Risks
- Low; docs/skill only
- Template may feel heavy for tiny changes (follow-up: add lightweight variant)

### Follow-ups
- Lightweight template variant for trivial PRs
- Reviewer handles/team mapping for automation

### Prompt History

#### Environment
Harness: codex
Model: gpt-5.2-codex
Thinking level: high
Terminal: iTerm.app 3.6.6
System: macOS 26.1

#### Prompts
_(truncated for this example — real PRs include full verbatim prompts)_

| ISO-8601 | Prompt |
| --- | --- |
| 2026-01-10T20:05:12Z | ``i need you to use cass/cm and search for all instructions related to creating PRs in the last 2 months or so...`` |
| 2026-01-10T20:34:59Z | ``can you draft a skill that helps us do this commit and PR workflow?`` |
| 2026-01-10T20:46:07Z | ``needs to indicate HUMAN WRITTEN intent. this absolutely MUST NOT be generated by the model EVER!!!!!`` |
| 2026-01-10T20:50:06Z | ``ok. use the skill and make a PR to my ai stack repo with this`` |

---

## Files

- `SKILL.md` — skill entry point
- `references/workflow-commit.md` — commit workflow steps
- `references/workflow-pr.md` — PR workflow steps
- `references/pr-human-template.md` — the PR template
- `references/commit-format.md` — commit message format
- `scripts/build_pr_body.sh` — environment metadata collector

## License

AGPL-3.0


path: scripts/build_pr_body.sh
content: #!/usr/bin/env bash
set -euo pipefail

harness="${AGENT_HARNESS:-}"
if [[ -z "$harness" ]]; then
  if [[ -n "${CODEX_MODEL:-}" || -d "${HOME}/.codex" ]]; then
    harness="codex"
  elif [[ -n "${CLAUDE_MODEL:-}" || -d "${HOME}/.claude" ]]; then
    harness="claude"
  elif [[ -n "${CURSOR_MODEL:-}" || -d "${HOME}/Library/Application Support/Cursor" ]]; then
    harness="cursor"
  else
    harness="unknown"
  fi
fi

model="${CODEX_MODEL:-${OPENAI_MODEL:-${ANTHROPIC_MODEL:-${CLAUDE_MODEL:-${CURSOR_MODEL:-${LLM_MODEL:-unknown}}}}}}"
thinking="${THINKING_LEVEL:-${CODEX_THINKING_LEVEL:-${OPENAI_THINKING_LEVEL:-unknown}}}"

terminal="${TERM_PROGRAM:-${LC_TERMINAL:-unknown}}"
terminal_ver="${TERM_PROGRAM_VERSION:-${LC_TERMINAL_VERSION:-}}"
if [[ -n "$terminal_ver" ]]; then
  terminal="${terminal} ${terminal_ver}"
fi

system="$(uname -s)"
if [[ "$system" == "Darwin" && -x /usr/bin/sw_vers ]]; then
  system="macOS $(/usr/bin/sw_vers -productVersion)"
elif command -v lsb_release >/dev/null 2>&1; then
  system="$(lsb_release -ds 2>/dev/null || uname -sr)"
else
  system="$(uname -sr)"
fi

cat <<EOF_OUT
Harness: ${harness}
Model: ${model}
Thinking level: ${thinking}
Terminal: ${terminal}
System: ${system}
EOF_OUT


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)