hanzlaahmadcheema/github-repo-agent-skill

GitHub Repo Agent Skill

An evidence-based operating contract for auditing, improving, releasing, and verifying GitHub repositories across any AI agent host (Antigravity, Copilot, Claude Code, Codex, OpenCode).

---

1. Core Operating Principles

1. CLAIM → VERIFY AGAINST REPO: Never assume README or documentation claims are true. Always inspect code, manifests, tests, hooks, and CI before trusting documentation.
2. THE 5-VERB LIFECYCLE:
   • AUDIT = READ (Gathers evidence, identifies discrepancies, zero side effects).
   • PREPARE = PROPOSE (Generates exact unified diffs and API payloads, does not mutate).
   • APPROVE = AUTHORIZE (Presents blast radius; waits for explicit human approval).
   • EXECUTE = MUTATE (Applies strictly what was approved; no out-of-scope actions).
   • VERIFY = PROVE (Compares Actual State against Approved State, not exit code == 0).
3. SCOPE ISOLATION:
   • User Prompt authorizes only the specifically requested task.
   • Audit Discoveries have zero authorization. Out-of-scope findings require a separate approval gate.
4. NEVER MUTATE DURING AUDIT: The audit phase is strictly read-only.
5. EVIDENCE-BACKED FINDINGS ONLY: An assertion without physical file/line/command evidence is rejected.
6. NO INVENTED FACTS: Never hallucinate repository descriptions, topics, or claims. Derive all metadata from verified repository reality.
7. BOUNDED SELF-HEALING: If an approved mutation fails during execution, the agent may self-heal automatically only within the approved files and scope, then must re-verify. Scope expansion requires fresh approval.

---

2. When to Use

Activate this skill when the user requests or intends:

• Full or targeted repository audits ("audit this repo", "review repository hygiene").
• Documentation verification ("check if README matches code", "fix README instructions").
• Git & GitHub configuration ("standardize topics", "clean up git hygiene", "set up CI workflow").
• Release preparation ("prepare release", "tag version", "generate release notes").
• Portfolio alignment ("evaluate if this repo is portfolio-ready", "prepare project summary").

---

3. Core Lifecycle Workflow

DISCOVER ──► AUDIT ──► PLAN ──► PREPARE ──► APPROVE ──► EXECUTE ──► VERIFY ──► REPORT [──► PORTFOLIO SYNC]

Phase 1: DISCOVER

1. GitHub Operational Identity & Access (Golden Path):
   • Parse local remote → Extract OWNER/REPO across SSH ([email protected]:...) and HTTPS (https://github.com/...).
   • Query gh auth status → Identify active authenticated GitHub account.
   • Query gh repo view OWNER/REPO → Verify repository existence, visibility, and mutation permissions.
   • Safety Invariant: If authenticated account differs from owner (e.g. organization or collaborator), verify access before planning. If inaccessible, warn and disable automatic remote mutations (can_mutate_remote: false).
   • Offline / No-Remote Fallback: If no remote exists, mark remote operations unavailable; local file remediation proceeds normally.
2. Detect repository root and current working tree status (git_state.py).
3. Detect the Product Shape (CLI, Library, Web App, Service, Agent Skill, Monorepo).
   • See references/shapes/heuristics.md for classification rules.

Phase 2: AUDIT (Read-Only)

1. Execute the 8-domain inspection:
   • Identity: Name, description, topics, homepage, visibility, license.
   • Structure: Manifests, lockfiles, entry points, tests, dead files.
   • Behavior: Verify README claims (install, build, test) against actual implementation.
   • Git: Working tree cleanliness, branch state, .gitignore, secret exposure.
   • GitHub: Workflows, issue/PR templates, rulesets, security configurations.
   • Security: Exposed credentials, workflow permissions, Dependabot alerts.
   • Quality: Test execution status, linting, formatting, CI status.
   • Distribution: Releases, packages, tags, demo availability.
   • See references/audit/checklist.md for the Core Audit Pack.
2. Format findings according to references/audit/contract.md:
   • Type: BUG, RISK, DRIFT, GAP, INCONSISTENCY, SUGGESTION.
   • Severity: P0 (Critical), P1 (High), P2 (Medium), P3 (Low), Suggestion.
3. Compile the dual-format output:
   • Structured data: audit-report.json conforming to references/schemas/audit-report.schema.json.
   • Executive Markdown report with the 4 mandatory sections: Bottom Line, Verified Clean, Findings, Coverage Limits.

Phase 3: PLAN

1. Prioritize findings by severity (P0 > P1 > P2 > P3).
2. Separate items requested by user prompt from audit-discovered items.
3. Comprehensive Remediation Scope: Remediation must never be restricted solely to application code. When audit findings include repository hygiene or GitHub configuration gaps, the remediation plan MUST explicitly categorize and include:
   • GitHub Metadata: Repository description (ID-002), topics/tags (ID-003), homepage (ID-004), metadata drift (GH-011).
   • Repository Hygiene Files: License (ID-005, ID-006), README accuracy & version consistency (DOC-001–DOC-006), CI/CD workflows (GH-001–GH-004), Dependabot (SEC-003), .gitignore (GIT-002).
   • GitHub Settings Proposals: Branch protection rulesets (GH-009), secret scanning settings (SEC-006).
   • Application & Code Fixes: Plaintext credentials (SEC-001), missing lockfiles (STR-002), test/lint scripts (QAL-*).
   • Scope Exclusion: GitHub Releases and release creation (DIST-*) are strictly skipped during standard remediation.
4. Define the proposed change set and classify risk tiers:
   • Local Reversible (editing docs, local workflows, license).
   • Remote Mutation (pushing branch, editing GitHub metadata/topics via gh repo edit).
   • High-Risk (changing visibility, deleting branches, force push).

Phase 4: PREPARE

1. Generate exact unified diffs for local files (README.md, LICENSE, .github/workflows/ci.yml, code).
2. Formulate exact GitHub CLI / API command payloads for remote changes (gh repo edit --description ... --add-topic ...).
3. Prepare settings proposal cards for branch protection or repository security configurations.
4. Record the PROPOSED_STATE object.

Phase 5: APPROVE (Human Gate)

1. Present the structured Change Set card to the user:
   • Target repository and branch.
   • Exact list of planned modifications.
   • Unified diff preview and external API payloads.
   • Blast-radius and rollback summary.
2. Halt and await explicit user confirmation: [Approve / Modify / Reject].
3. Upon approval, freeze the APPROVED_STATE object.

Phase 6: EXECUTE (Mutation)

1. If modifying files locally: apply the approved unified diffs.
2. If committing: stage specific files (git add <file>, never git add .), generate Conventional Commit message.
3. If mutating remote metadata/settings: execute approved commands (gh repo edit, API calls) under explicit REMOTE_MUTATION authorization.
4. If an execution step fails:
   • Diagnose error from stderr.
   • Attempt self-healing only within the approved scope and files.
   • If fix requires out-of-scope changes, halt immediately and request revised approval.

Phase 7: VERIFY (Proof)

1. Query the ACTUAL_STATE directly from the filesystem, git, or GitHub API.
2. Perform exact assertion: ACTUAL_STATE == APPROVED_STATE.
3. If discrepancies exist, report VERIFICATION_FAILED with evidence and propose rollback.
4. If matching, mark status as VERIFIED_SUCCESS.

Phase 8: REPORT

1. Output final executive summary detailing:
   • What was changed (commits, modified files, metadata updated).
   • Verification proof (actual state verified).
   • Remaining unaddressed audit findings.
   • Next recommended steps.

Phase 9: PORTFOLIO SYNC (Optional, Event-Driven)

1. If repo changes alter portfolio-relevant fields (status, description, tech stack, demo URL):
   • Generate normalized project summary conforming to references/schemas/portfolio.schema.json.
   • Prompt user: "Portfolio impact detected. Prepare sync proposal? [Yes / Skip]".
   • Never sync automatically without separate authorization.
   • See references/portfolio/sync.md.

---

4. Progressive Disclosure & Reference Index

To maintain token efficiency, deep domain guidance is organized in references/ and loaded on demand:

• Audit & Evaluation:
  • references/audit/contract.md — Check object schema, evidence levels, finding taxonomy.
  • references/audit/checklist.md — Complete Core Audit Pack across all 8 domains.
  • references/audit/severity.md — Exact definitions for P0, P1, P2, P3, and Suggestions.
  • references/audit/evidence.md — Evidence hierarchy, direct/derived/inferred proof, coverage limits.
• Product Shapes:
  • references/shapes/heuristics.md — Shape detection matrix (CLI, Library, Web App, Service, Agent Skill, Monorepo).
• Git & GitHub Workflows:
  • references/git/hygiene.md — .gitignore standards, secret avoidance, branch naming.
  • references/git/mutation.md — Atomic staging, Conventional Commits, no-force-push rules.
  • references/github/metadata.md — Topics taxonomy, description constraints, homepage sync.
  • references/github/security.md — Dependabot, secret scanning, Actions token permissions.
• Documentation & Release:
  • references/documentation/readme-standards.md — 10/10 README anatomy (Identify → Evaluate → Use → Engage).
  • references/release/workflow.md — Semantic versioning, tag creation, release notes generator.
• Portfolio:
  • references/portfolio/sync.md — Normalized project descriptor & event-driven sync pipeline.
• Schemas:
  • references/schemas/audit-report.schema.json — Full audit report schema.
  • references/schemas/finding.schema.json — Finding object schema.
  • references/schemas/changeset.schema.json — Change set & approval schema.
  • references/schemas/portfolio.schema.json — Normalized project schema.

---

5. Deterministic Scripts Helper Index

Deterministic operations are encapsulated in scripts/:

• python3 scripts/audit/audit_runner.py — Runs the static inspection suite and generates audit-report.json.
• python3 scripts/audit/claim_verifier.py — Verifies documented README commands against package manifests.
• python3 scripts/audit/secret_scanner.py — Fast regex scanner for tracked tokens, private keys, and .env files.
• python3 scripts/git/git_state.py — Queries working tree, branch drift, and untracked artifacts.
• python3 scripts/verify/state_verifier.py — Compares ACTUAL_STATE against APPROVED_STATE.