Skip to content

TidyFactor Documentation

TidyFactor GitHub — Operations & Rulesets

🐙 TidyFactor GitHub `v1.1.0`¶

GitHub Platform Operations, Open Source Community, Contributor Experience (CX), Governance & Anti-Slop README Engine¶

Transforming GitHub from a passive Git remote into a governed, secure, automated, and sustainable open-source product hub.

🌐 Official Website • 📚 Documentation • 🤝 Partner (Alwkala) • ⚡ Commands • 🛡️ Security Guarantees • 📖 Read in Arabic (بالعربية)

[!NOTE] TidyFactor GitHub is an enterprise-grade AI coding agent skill designed for Google Antigravity, Claude Code, Cursor, Codex, and Windsurf. It operates across the entire GitHub platform hierarchy: Account ➔ Organization ➔ Repository ➔ Code ➔ Collaboration ➔ Security ➔ Contributor Experience (CX) ➔ Open Source Governance.

🌟 Value Proposition & The 5-Layer Engine¶

                               ┌─────────────────────────────────────────┐
                               │            TIDYFACTOR GITHUB            │
                               │  GitHub Platform Operations & Intel     │
                               └────────────────────┬────────────────────┘
                                                    │
        ┌───────────────────┬───────────────────────┼───────────────────────┬───────────────────┐
        │                   │                       │                       │                   │
  ┌─────▼───────┐     ┌─────▼─────────┐       ┌─────▼─────────┐       ┌─────▼─────────┐   ┌─────▼─────────┐
  │ OPERATIONS  │     │  GOVERNANCE   │       │    CONTENT    │       │    STYLING    │   │  OSS & INTEL  │
  ├─────────────┤     ├───────────────┤       ├───────────────┤       ├───────────────┤   ├───────────────┤
  │• Org & Repos│     │• Rulesets     │       │• README UX    │       │• Visual Lang  │   │• 10-Axis Audit│
  │• Members/Team│    │• CODEOWNERS   │       │• Issue Forms  │       │• Badge Matrix │   │• CX Onboarding│
  │• Branches   │     │• Security/2FA │       │• PR Workflows │       │• Typography   │   │• Good 1st Iss │
  │• Actions/CI │     │• LeastPrivileg│       │• Docsify/Wiki │       │• Social Banner│   │• RFC / ADR Log│
  │• Releases/Pkg│    │• GOVERNANCE.md│       │• Changelogs   │       │• Scannability │   │• Bus Factor   │
  └─────────────┘     └───────────────┘       └───────────────┘       └───────────────┘   └───────────────┘

For Developers & Tech Leads	For AI Coding Agents	For Organizations & Maintainers
10-Axis Open Source Health Scorecard: Evaluates repo readiness (0-100) across identity, CX, security, CI/CD, and governance.	Token-Efficient Routing: Compact router `SKILL.md` (~340 tokens) with Contextual Decision Layer (`/brief`).	Organization Governance: Team hierarchies, permission matrices, and Least Privilege enforcement.
Contributor Experience (CX): Streamlines onboarding to < 30m with curated Good First Issues and a 6-tier Contributor Ladder.	Triple Safety Modes: `AUDIT` (read-only), `PLAN` (dry-run diffs), and `APPLY` with explicit confirmation gates.	Architecture Decisions: Full RFC (`docs/rfcs/`) and ADR (`docs/adrs/`) lifecycle pipelines.
Supply Chain Security: Automates SHA pinning for GitHub Actions and top-level read-only permissions.	100% Deterministic Tools: Native Python/Node CLI utilities (`oss_audit.py`, `repo_audit.py`, `readme_linter.py`).	Bilingual by Design: Native English and Arabic (RTL) documentation, rulesets, and issue templates.

🛡️ Triple Execution Modes & Safety Gate¶

To protect repositories and organizations from accidental mutations:

graph TD
    A[User Intent / Command] --> B{Execution Mode}
    B -->|AUDIT Mode| C[Read-Only: Compute 10-Axis Readiness Scorecard]
    B -->|PLAN Mode| D[Simulation: Generate Diff & Proposed gh Commands]
    B -->|APPLY Mode| E{Is Action Destructive / High-Risk?}
    E -->|Yes| F[Explicit Confirmation Gate]
    F -->|User Confirms| G[Execute Mutation]
    F -->|User Cancels| H[Abort & Save Report]
    E -->|No: Standard Scaffolding| G

High-Risk Operations Requiring Explicit Confirmation:
Deleting repositories or production branches.
Granting or elevating Admin roles.
Changing repository visibility (Private ➔ Public).
Transferring repository ownership.
Disabling or modifying active branch protection Rulesets.

⚡ Commands & Capabilities Matrix (22 Commands)¶

Command	Intent & User Request	Loaded Workflows & Memory	Output Artifact
`/brief`	Strategic discovery & baseline configuration	`workflows/brief-discovery.md` `memory/decision-points.md`	`.tidyfactor/github-brief.md`
`/audit`	9-Dimension repo & org health audit	`workflows/run-repo-audit.md` `memory/maturity-model.md`	Health Scorecard & Remediation Report
`/oss`	10-Axis Open Source Readiness & Doctor	`workflows/run-oss-audit.md` `memory/oss-readiness-rubric.md`	OSS Scorecard (0-100) & Diagnosis
`/cx`	Contributor Experience (CX) & Onboarding	`workflows/optimize-cx-onboarding.md` `memory/cx-framework.md`	`CONTRIBUTING.md`, Contributor Ladder
`/gfi`	Good First Issue discovery & scoping	`workflows/triage-good-first-issues.md` `memory/cx-framework.md`	Beginner-Ready Issues with Effort Score
`/rfc`	Request for Comments & ADR decisions	`workflows/author-rfc-adr.md` `memory/oss-governance-models.md`	`docs/rfcs/.md`, `docs/adrs/.md`
`/org`	Org architecture, teams & permission matrix	`workflows/setup-org-hierarchy.md` `memory/permission-matrix.md`	Team Mapping & RBAC Audit
`/repo`	Repository factory & portfolio lifecycle	`workflows/scaffold-repository.md` `memory/maturity-model.md`	Standard Repository Skeleton
`/branch`	Branch strategy (Trunk, Flow) & naming	`workflows/configure-rulesets.md` `memory/branch-strategies.md`	Branch Naming & Flow Policy
`/ruleset`	GitHub Rulesets & branch protection	`workflows/configure-rulesets.md` `rules/gov-rules.md`	Ruleset JSON Configurations
`/issue`	YAML Issue Forms & label taxonomy	`workflows/setup-issue-forms.md` `memory/issue-taxonomy.md`	`.github/ISSUE_TEMPLATE/*.yml`
`/pr`	PR templates, CODEOWNERS & review flows	`workflows/setup-pr-template.md` `rules/gov-rules.md`	`.github/PULL_REQUEST_TEMPLATE.md`
`/action`	Actions CI/CD, SHA pinning & caching	`workflows/audit-actions-ci.md` `rules/ci-rules.md`	`.github/workflows/ci.yml`
`/security`	Dependabot, secret scanning & policies	`workflows/harden-security.md` `rules/sec-rules.md`	`.github/dependabot.yml`, `SECURITY.md`
`/community`	Community health files & OSS maintainer mode	`workflows/setup-community-health.md` `memory/maturity-model.md`	`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
`/readme`	README Experience Engine & Anti-Slop	`workflows/craft-readme.md` `rules/content-rules.md`	Developer-first `README.md`
`/style`	Visual tokens, badges & social preview	`workflows/design-social-preview.md` `memory/repo-design-tokens.md`	Social Card Spec (1280x640) & Badges
`/release`	SemVer automation & CHANGELOG SSOT	`workflows/automate-release.md` `memory/maturity-model.md`	Atomic Version Bump & Tag
`/project`	GitHub Projects (v2), views & roadmaps	`workflows/manage-projects.md` `memory/maturity-model.md`	Project Fields & Views Schema
`/discover`	Repository Discoverability (RDO) & SEO	`workflows/optimize-discoverability.md` `memory/rdo-matrix.md`	Curated Topics (8-12) & Description
`/incident`	Production incident triage & postmortem	`workflows/handle-incident.md` `memory/security-baseline.md`	Suspect Commit Diff & Postmortem Doc
`/blueprint`	Blueprint gap analysis & alignment	`workflows/apply-blueprint.md` `memory/decision-points.md`	Gap Analysis & Alignment Report

🔒 Security & Supply Chain Invariants¶

All workflows generated by tidyfactor-github enforce strict security standards:

# Example of a fully compliant CI workflow
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout Code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup Node.js
        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
        with:
          node-version: "20"
          cache: "npm"

      - name: Run Tests
        run: npm test

🚀 Installation & Quick Injection¶

One-Command Project Injection¶

npx @tidyfactor/cli-github

Manual Agent Workspace Injection¶

Place the skill inside your agent customization root:

.agents/skills/tidyfactor-github/