repo-hc

repo-hc is a developer npm package for automated GitHub housekeeping.
It provides AI-agent guidance and workflow contracts to keep repositories clean, secure, and well documented.

Important

repo-hc is published on npm. This repository remains the source of truth for architecture, rules, and documentation.

Table of Contents

• Vision
• AI Agent Workflow System
• Installation
• Bootstrap Behavior
• What The Package Will Cover
• Documentation System
• Repository Layout
• Contributing
• License

Vision

repo-hc is designed to standardize how an AI agent maintains a repository by enforcing repeatable housekeeping practices:

• plan-first execution
• branch discipline
• security-aware changes
• synchronized documentation
• explicit auditability of AI-assisted work

Primary optimization targets: OpenAI Codex and Anthropic Claude CLI.

AI Agent Workflow System

AI-assisted work in this repository is guided by AGENTS.md, CLAUDE.md, and the local .agents/ knowledge base:

• AGENTS.md: baseline collaboration, architecture, security, and documentation rules
• CLAUDE.md: Claude CLI baseline guidance aligned to repository rules
• .agents/rules/: user-defined operational rules
• .agents/skills/: reusable SKILL.md playbooks
• .agents/learnings/: implementation learnings and decisions
• .agents/prompts/: sanitized source prompts for traceability
• .agents/plans/: scoped feature implementation plans

Installation

npm view repo-hc version
pnpm add repo-hc
pnpm exec repo-hc init

Install directly from npm:

• package name: repo-hc

Tip

Start every AI-assisted task with the agent baseline file:

• Codex: AGENTS.md
• Claude CLI: CLAUDE.md Then continue with .agents/README.md, then docs/README.md. The effective behavior rules are user-defined in /.agents/rules.

Bootstrap Behavior

Run repo-hc init after installation to bootstrap these assets into the consumer project root:

• .agents/
• docs/
• AGENTS.md (canonical)

Claude CLI note:

• CLAUDE.md is maintained in this repository for Claude CLI workflows.
• Current package bootstrap guarantees AGENTS.md as canonical baseline file.

For .agents/, repository-internal non-example files are excluded from transfer in:

• .agents/rules/
• .agents/learnings/
• .agents/plans/
• .agents/prompts/

Only each folder's examples/ content is copied for those areas.

When repo-hc init runs interactively, it also asks whether common agent files should be hidden in VS Code Explorer.
If confirmed, it creates or updates .vscode/settings.json with files.exclude entries for:

• .agents
• AGENTS.md

Existing files are preserved by default (non-destructive copy). To run or re-run:

pnpm exec repo-hc init

To overwrite existing files intentionally:

pnpm exec repo-hc init --force

What The Package Will Cover

• repository hygiene workflows for AI agents
• change planning and branch policies
• documentation synchronization rules
• security and secret-handling safeguards
• reusable prompts, learnings, and skills integration

Documentation System

Project documentation is centralized in docs/ and organized by feature, audience, and architecture diagrams:

• docs/README.md: docs index and reading order
• docs/project/: global standards and rules
• docs/workflow/: contributor workflow guides
• docs/housekeeping/: package-specific developer and user docs
• docs/mermaid/: architecture and workflow diagrams

Repository Layout

• AGENTS.md: baseline guidance for AI-assisted implementation
• CLAUDE.md: baseline guidance for Anthropic Claude CLI workflows
• .agents/: internal rules, prompts, learnings, plans, and skills
• docs/: public project documentation and Mermaid diagrams
• CONTRIBUTING.md: contributor workflow
• SECURITY.md: vulnerability reporting and security baseline

Contributing

Please follow the process in CONTRIBUTING.md.

Short version:

1. Create a dedicated feature branch.
2. Implement your intended change or extension directly, preferably as reusable .agents updates (including rules, examples, prompts, learnings, or skills for agents like Claude, Kiro, Kilo, etc.).
3. Keep documentation in sync with every behavior or workflow change.

License

Licensed under AGPL-3.0. See LICENSE.txt.