From forgeproof
Create provenance-tracked code from a GitHub issue with a cryptographically signed audit trail. Use when the user asks to "forgeproof an issue", "create a provenance bundle", "generate auditable code from an issue", or wants cryptographically signed proof of AI-generated work. Supports Python, TypeScript/JavaScript, and Go projects. Invoke with an issue number or without one to browse assigned issues.
How this skill is triggered — by the user, by Claude, or both
Slash command
/forgeproof:forgeproof [issue-number][issue-number]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Execute a cryptographically signed development workflow. Every action is
Execute a cryptographically signed development workflow. Every action is
recorded in a tamper-evident Ed25519 hash chain. The output is an .rpack
provenance bundle that proves what was done, why, and that nothing was
altered after signing.
The provenance engine script is at ${CLAUDE_PLUGIN_ROOT}/skills/forgeproof/scripts/forgeproof.py.
Reference it as $FP in all commands below for brevity.
If $ARGUMENTS is empty (no issue number provided):
python $FP issues --assignee @me$ISSUE to the chosen issue number and continueIf $ARGUMENTS contains an issue number, set $ISSUE to that number and continue.
Run the dependency check:
python $FP preflight
If any check fails, stop and tell the user exactly what is missing and how to install it. Do not proceed until all checks pass.
Then detect the project toolchain:
python $FP detect
Parse the JSON output. Store the detected test_runner.command and linter.command for use in Phase 3. If no language is detected, ask the user to specify their test command and lint command.
Fetch the issue:
gh issue view $ISSUE --json title,body,labels,assignees,comments
Read the issue body carefully. Extract structured requirements from it. Number them as REQ-1, REQ-2, etc. Each requirement should be a single, testable statement.
If the issue body is vague or lacks clear requirements, propose reasonable requirements based on the title and body, and ask the user to confirm or adjust.
Scan the repository structure using Glob and Grep to understand the codebase. Identify relevant files, patterns, and conventions.
Propose an implementation plan:
STOP and present the plan to the user. Wait for approval before proceeding. The user may adjust the plan, add constraints, or reject parts of it. This is a conversation, not an automated pipeline.
Once the plan is approved, begin implementation.
Before writing any code, check for a .gitignore:
ls .gitignore
If missing, warn the user: "No .gitignore found. Generated files like __pycache__/ and *.pyc may be committed. Consider creating one before proceeding."
Initialize the provenance chain:
python $FP init --issue $ISSUE --force --data '{"title": "<issue title>", "requirements": ["REQ-1: <text>", "REQ-2: <text>"]}'
The --force flag safely handles re-runs by cleaning up any prior chain for this issue.
Check for an existing local branch and clean up if needed:
git branch --list forgeproof/$ISSUE
If it exists, delete it: git branch -D forgeproof/$ISSUE
Check for an existing remote branch (note this for the push step later):
git ls-remote --heads origin forgeproof/$ISSUE
Create the feature branch:
git checkout -b forgeproof/$ISSUE origin/main
Then record it:
python $FP record --issue $ISSUE --action branch-create --data '{"branch": "forgeproof/$ISSUE", "base": "main", "base_sha": "<sha>"}'
Implement the changes. After EVERY file you create or modify, record it:
python $FP record --issue $ISSUE --action file-edit --data '{"path": "<filepath>", "operation": "create|modify", "sha256": "<hash>"}'
Compute the sha256 with: sha256sum <filepath> | cut -d' ' -f1
Log significant decisions as you work. When you choose an approach, skip an alternative, or make a non-obvious judgment call:
python $FP record --issue $ISSUE --action decision --data '{"context": "<what you were deciding>", "choice": "<what you chose>", "rationale": "<why>"}'
Write tests that cover each requirement. Record test file creation as file-edit blocks.
.forgeproof/ files directly — only through the Python scriptsRun the test suite using the command detected in Phase 0:
<detected test command> 2>&1
Record the results:
python $FP record --issue $ISSUE --action test-result --data '{"suite": "<name>", "passed": <N>, "failed": <N>, "coverage": {"REQ-1": ["<test_name>"], "REQ-2": ["<test_name>"]}, "failed_tests": ["<test_name if any>"]}'
Run the linter using the command detected in Phase 0:
<detected lint command> 2>&1
Record lint results:
python $FP record --issue $ISSUE --action lint-result --data '{"tool": "<name>", "errors": <N>, "warnings": <N>}'
If tests or linting fail, attempt ONE auto-fix cycle:
If still failing after the retry, proceed to Phase 4 anyway. The bundle is always produced — the evaluation status will reflect the failures.
Stage ONLY the files recorded in the provenance chain and the .forgeproof/ directory.
Do NOT use git add -A or git add . — this prevents committing generated files like
__pycache__/, *.pyc, or other untracked artifacts.
git add <file1> <file2> ...
git add .forgeproof/
git commit -m "forgeproof(#$ISSUE): <concise description>"
The file list comes from the file-edit records you made during Phase 2. Stage each
file path that appeared in a --action file-edit --data '{"path": "..."}' call.
Finalize the chain and build the .rpack bundle:
python $FP finalize --issue $ISSUE --commit $(git rev-parse HEAD)
This command:
.rpack bundle with all artifacts, requirements, decisions, and evaluation dataReport the result to the user. Include:
.rpack file/forgeproof-push to create a PR, or /forgeproof-verify to verify the bundleDetailed specifications are in references/:
chain-format.md — Hash chain block format and action typesrpack-format.md — .rpack bundle JSON schematoolchain-detection.md — Supported languages and detection logicnpx claudepluginhub ryanjmichie-git/forgeproof-plugin --plugin forgeproofProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.