coding-agent-skills 0.2.13 → 0.2.14

package/skills/github-handoff/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: github-handoff
+description: Prepare read-only GitHub handoff evidence from local Git metadata. Use when Codex needs to summarize branch state, HEAD, tags at HEAD, remote names, and changed-file status before a separately approved pull request, release, or GitHub workflow handoff without creating commits, pushes, tags, pull requests, API calls, token reads, or file changes.
+---
+
+# GitHub Handoff
+
+## Purpose And Use
+
+Use this skill to produce a local, audit-only handoff report before a human or separately approved workflow performs GitHub work.
+
+The skill is for local Git evidence only. It does not create pull requests, publish releases, push branches, inspect tokens, or call GitHub APIs.
+
+## Inputs
+
+Required:
+
+- Project root.
+
+Optional:
+
+- Project adapter declaration that enables `github-handoff`.
+- Human-provided handoff intent.
+
+Do not assume:
+
+- GitHub authentication is available.
+- Local commits are pushed.
+- CI status, review status, or PR state is known.
+- Remote URLs are safe to print.
+
+## Procedure
+
+1. Confirm the project root exists.
+2. Validate the project adapter when one is present.
+3. If an adapter exists but does not enable `github-handoff`, report `partial` and do not list changed files.
+4. Inspect local Git metadata only: root, branch state, current branch, HEAD, tags at HEAD, remote names, and status entries.
+5. Redact secret-bearing changed paths such as `.env`, key files, credential paths, or token paths.
+6. Summarize changed-file counts by status.
+7. Record skipped and not-verified GitHub state honestly.
+8. State refused behavior clearly.
+
+## Evidence, Recovery, And Dependencies
+
+Expected evidence:
+
+- Git root.
+- Branch state.
+- Current branch.
+- HEAD or short HEAD.
+- Tags at HEAD.
+- Remote names only, not remote URLs.
+- Changed-file summary.
+- Redacted path count when applicable.
+
+Recovery:
+
+- If the directory is not a Git repository, return `failed` with no mutation.
+- If Git status is unavailable, return a warning and preserve partial evidence.
+- If adapter validation fails, fail closed.
+
+Dependencies:
+
+- Local Git command-line tool.
+- Node.js 20+ for the packaged renderer.
+
+## Approval Boundary
+
+This skill is audit-only.
+
+Allowed:
+
+- Read local Git metadata.
+- List changed-file paths unless they are secret-bearing.
+- Validate project adapter metadata.
+- Render a handoff report.
+
+Forbidden:
+
+- Commit.
+- Push.
+- Tag.
+- Checkout, reset, rebase, merge, stash, restore, or clean.
+- Create pull requests.
+- Create releases.
+- Call GitHub APIs.
+- Read tokens, `.env`, `.env.*`, `.npmrc`, keys, or credential files.
+- Print remote URLs.
+- Change project files.
+
+## Completion
+
+Complete only after a report states what was verified, what was skipped, and what was not verified.
+
+The completion boundary must say that no commit, push, tag, branch change, pull request creation, GitHub API mutation, token read, secret-file read, or project write occurred.

package/skills/github-handoff/adapter-interface.md

@@ -0,0 +1,18 @@
+# GitHub Handoff Adapter Interface
+
+Adapters may enable `github-handoff` as an audit-only skill.
+
+Adapters may narrow:
+
+- Required evidence labels.
+- Ignored path labels.
+- Documentation precedence used as human context.
+
+Adapters must not:
+
+- Permit commits, pushes, tags, pull request creation, release creation, or GitHub API mutation.
+- Permit token reads.
+- Permit secret-file reads.
+- Suppress warnings or failures.
+- Redefine completion.
+- Escalate the skill out of audit-only mode.

package/skills/github-handoff/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: GitHub Handoff
+short_description: Prepare local Git handoff evidence without GitHub mutation.
+default_prompt: Prepare a GitHub handoff report as an audit-only pass without modifying files, committing, pushing, tagging, creating pull requests, reading tokens, or calling GitHub APIs.

package/skills/github-handoff/checklist.md

@@ -0,0 +1,10 @@
+# GitHub Handoff Checklist
+
+- Confirm the project root.
+- Validate adapter metadata if present.
+- Inspect local Git state only.
+- Summarize changed files without reading file contents.
+- Redact secret-bearing paths.
+- Do not print remote URLs.
+- Report not-verified GitHub state.
+- Confirm no mutation occurred.

package/skills/github-handoff/evidence-template.md

@@ -0,0 +1,16 @@
+# GitHub Handoff Evidence Template
+
+- Skill: `github-handoff`
+- Status: `complete`, `partial`, or `failed`
+- Project root:
+- Git root:
+- Branch state:
+- HEAD:
+- Tags at HEAD:
+- Remote names:
+- Changed-file summary:
+- Redacted path count:
+- Skipped:
+- Not verified:
+- Refused behavior:
+- Changed state: no project, Git, GitHub, dependency, runtime, service, or remote state changed.

package/skills/github-handoff/examples.md

@@ -0,0 +1,19 @@
+# GitHub Handoff Examples
+
+## Safe Examples
+
+```bash
+coding-agent-skills github-handoff /path/to/project
+```
+
+```bash
+node scripts/render-github-handoff.mjs /path/to/project
+```
+
+## Unsafe Examples
+
+- Create a pull request.
+- Push the current branch.
+- Tag the release.
+- Read GitHub tokens.
+- Print configured remote URLs.

package/skills/github-handoff/failure-modes.md

@@ -0,0 +1,8 @@
+# GitHub Handoff Failure Modes
+
+- Project root is not a Git repository.
+- Adapter exists but does not enable `github-handoff`.
+- Adapter validation fails.
+- Git status is unavailable.
+- Secret-bearing changed paths are present and must be redacted.
+- Remote PR, CI, and review state cannot be verified without separately approved GitHub access.

package/tests/fixtures/github-handoff/adapter-project/.coding-agent/adapters/github-handoff-fixture/adapter.json

@@ -0,0 +1,56 @@
+{
+  "adapterId": "github-handoff-fixture",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-github-handoff",
+    "detection": {
+      "rootMarkers": [
+        {"kind": "file", "path": "package.json"},
+        {"kind": "file", "path": "README.md"}
+      ],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "github-handoff",
+      "compatibleVersions": ["0.2.3", "0.2.x"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["README.md", "package.json", "src"],
+    "ignoredPaths": ["node_modules", "dist", "build", "tmp"],
+    "documentationPrecedence": ["README.md"],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["branch state", "HEAD", "working-tree state", "changed-file summary", "handoff summary"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["npm"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/github-handoff/adapter-project/.coding-agent/skills.json

@@ -0,0 +1,23 @@
+{
+  "declarationVersion": "1.0.0",
+  "projectId": "fixture-github-handoff",
+  "adapterRoot": ".coding-agent/adapters",
+  "adapterSchemaVersion": "1.0.0",
+  "core": {
+    "id": "coding-agent-skills",
+    "expectedVersion": "0.2.3",
+    "versionPin": ">=0.2.3 <0.3.0"
+  },
+  "compatibleSkillIds": ["github-handoff"],
+  "adapters": [
+    {
+      "id": "github-handoff-fixture",
+      "version": "1.0.0",
+      "skillIds": ["github-handoff"]
+    }
+  ],
+  "validationCommand": "node <shared-core>/scripts/validate-project-adapters.mjs <project-root>",
+  "evidenceOutput": ".coding-agent/evidence",
+  "approvalPolicyReference": ".coding-agent/approval-policy.md",
+  "noSecrets": true
+}

package/tests/fixtures/github-handoff/adapter-project/README.md

@@ -0,0 +1,3 @@
+# GitHub Handoff Adapter Fixture
+
+Synthetic adapter-enabled project used to test handoff metadata.

package/tests/fixtures/github-handoff/adapter-project/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "github-handoff-adapter-fixture",
+  "private": true
+}

package/tests/fixtures/github-handoff/adapter-project/src/index.js

@@ -0,0 +1 @@
+export const adapterFixture = "github-handoff";

package/tests/fixtures/github-handoff/static-project/README.md

@@ -0,0 +1,3 @@
+# GitHub Handoff Static Fixture
+
+Synthetic project used to test local Git handoff summaries.

package/tests/fixtures/github-handoff/static-project/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "github-handoff-static-fixture",
+  "private": true
+}

package/tests/fixtures/github-handoff/static-project/src/index.js

@@ -0,0 +1 @@
+export const fixture = "github-handoff";

package/tests/fixtures/triggers/cases.json

@@ -79,6 +79,18 @@
       "expectedSkill": "migration-review",
       "notSkills": ["deployment-preflight", "runtime-truth"]
     },
+    {
+      "id": "github-handoff-report",
+      "prompt": "Prepare a GitHub handoff report from local branch state and changed files without pushing.",
+      "expectedSkill": "github-handoff",
+      "notSkills": ["git-preflight", "build-verify"]
+    },
+    {
+      "id": "github-handoff-pr-evidence",
+      "prompt": "Summarize handoff evidence for a future PR without creating the pull request.",
+      "expectedSkill": "github-handoff",
+      "notSkills": ["runtime-truth", "deployment-preflight"]
+    },
     {
       "id": "build-after-implementation",
       "prompt": "The implementation is finished. Run the existing typecheck, tests, and build.",
@@ -131,7 +143,7 @@
       "id": "negative-deploy",
       "prompt": "Deploy this application to production.",
       "expectedSkill": null,
-      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "api-contract-audit", "migration-review", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
+      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "api-contract-audit", "migration-review", "github-handoff", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
     },
     {
       "id": "negative-install",
@@ -143,7 +155,7 @@
       "id": "negative-publish",
       "prompt": "Commit these files and publish the branch.",
       "expectedSkill": null,
-      "notSkills": ["git-preflight"]
+      "notSkills": ["git-preflight", "github-handoff"]
     },
     {
       "id": "negative-restart",

package/tests/trigger/README.md

@@ -12,6 +12,8 @@
   build verification.
 - Static migration/schema review must trigger `migration-review`, not runtime truth,
   deployment, or migration execution.
+- Local GitHub handoff evidence must trigger `github-handoff`, not publication,
+  pull request creation, or Git mutation.
 - Local validation must trigger `build-verify` only when project-native checks are requested.
 - Git readiness must trigger `git-preflight`, not publication.
 - Process/listener/health questions must trigger `runtime-truth`, not restart behavior.

package/work-ledger.md

@@ -4,13 +4,13 @@
 
 - Repository: `coding-agent-skills`
 - Branch: `main`
-- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`, `build-verify`, `git-preflight`, `runtime-truth`, `llm-drift-control`
+- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`, `github-handoff`, `build-verify`, `git-preflight`, `runtime-truth`, `llm-drift-control`
 - Adapter discovery, project adapter installation, stale-pin detection, upgrade evidence, compatibility-chain validation, evidence-bundle verification, retention policy, provenance design, archive-report rendering, archive-index fixtures, retention-expiry advisory reporting, and detached-signature verification planning are implemented.
 - Real-project adapter adoption readiness is documented as a planning-only approval gate.
 - First external project-owned adapter adoption completed for `/home/oneclickwebsitedesignfactory/tax-lien-platform` at candidate commit `c548b1a6cbb3455a70b89d0e301e22435bfccac9`.
 - The adopted adapter is `repo-map` only, docs/metadata-only, and contains no commands, runtime checks, build/test/package behavior, platform/deployment behavior, or secret-aware behavior.
 - The shared repository does not contain real adapter manifests; real project adapters remain owned by their project repositories.
-- Public npm package release `v0.2.13` exposes the dependency-free
+- Public npm package release `v0.2.14` exposes the dependency-free
   `coding-agent-skills` CLI under MIT license.
 - `route-trace` is implemented as an audit-only static route tracing skill.
 - `env-audit` is implemented as an audit-only value-free environment variable name mapping
@@ -20,19 +20,20 @@
   skill.
 - `migration-review` is implemented as an audit-only static migration and schema evidence
   review skill.
+- `github-handoff` is implemented as an audit-only local Git handoff evidence skill.
 - Builder-mode approval: complete the remaining read-only skill wave for
   `coding-agent-skills` itself. Real-world project execution constraints remain unchanged.
 
 ## Last Completed Version
 
-`v0.2.13`
+`v0.2.14`
 
 ## Current Recommended Milestone
 
-The `migration-review` public npm release is in progress under builder-mode approval.
+The `github-handoff` public npm release is in progress under builder-mode approval.
 Continue the remaining read-only skill wave one release at a time unless a real safety,
 validation, publication, or authentication boundary appears. The next approved wave item is
-`github-handoff-skill`.
+`deployment-preflight-skill`.
 
 ## Allowed Next Actions
 
@@ -104,12 +105,21 @@ No next runner command is currently queued.
 
 No autonomous maintainer-loop run has been recorded yet.
 
+### 2026-07-03T13:00:00Z
+
+- Latest tag observed: `v0.2.13`
+- Implemented milestone: `github-handoff` audit-only local Git handoff evidence skill and CLI command.
+- Required permission: `builder-mode-skill-implementation`
+- Validation result: pass pending final publication evidence
+- Next recommended milestone: continue builder-mode wave with `deployment-preflight-skill`
+  after `v0.2.14` publication completes.
+
 ### 2026-07-03T12:00:00Z
 
 - Latest tag observed: `v0.2.12`
 - Implemented milestone: `migration-review` audit-only static migration and schema evidence review skill and CLI command.
 - Required permission: `builder-mode-skill-implementation`
-- Validation result: pass pending final publication evidence
+- Validation result: passed; `v0.2.13` commit, tag, npm publication, registry smoke, npm exec, and GitHub Release completed
 - Next recommended milestone: continue builder-mode wave with `github-handoff-skill`
   after `v0.2.13` publication completes.