repo-hc 0.1.0

package/.agents/README.md

@@ -0,0 +1,68 @@
+# Agents Docs Guide
+
+## Purpose
+
+This folder stores reusable agent knowledge for consistent, safe, and fast collaboration.
+
+- `rules/`: mandatory policies for documentation and workflow
+- `plans/`: scoped implementation plans used before coding
+- `learnings/`: reusable implementation learnings and outcomes
+- `prompts/`: sanitized source prompt context
+- `skills/`: task-specific playbooks (`SKILL.md`)
+
+## How To Use
+
+1. Read relevant files under `rules/` first.
+2. Check `skills/` and apply matching skills before implementation.
+3. Create or update a plan in `plans/` before coding feature work.
+4. When adding a learning, add the matching sanitized prompt where useful.
+5. Mask sensitive data in all stored content.
+6. Keep all text in English unless explicitly requested otherwise.
+7. Update this README whenever `.agents` files are added, removed, or renamed.
+
+## Naming Convention
+
+- Prefer date-prefixed plan files: `YYYY-MM-DD-<topic>.md`.
+- Keep filenames concise and topic-specific.
+- Keep one clear topic per file.
+
+## Current Index
+
+### Plans
+
+- [2026-03-11-github-housekeeping-doc-refresh.md](./plans/2026-03-11-github-housekeeping-doc-refresh.md)
+- [2026-03-11-publishable-repo-hc-package-bootstrap.md](./plans/2026-03-11-publishable-repo-hc-package-bootstrap.md)
+- [examples/2026-03-11-add-docs-workflow-guides.md](./plans/examples/2026-03-11-add-docs-workflow-guides.md)
+- [examples/2026-03-11-central-api-docs-mermaid.md](./plans/examples/2026-03-11-central-api-docs-mermaid.md)
+
+### Learnings
+
+- [03_repo-hc-install-bootstrap.md](./learnings/03_repo-hc-install-bootstrap.md)
+- [examples/01_workspace-peer-dependency-resolution.md](./learnings/examples/01_workspace-peer-dependency-resolution.md)
+- [examples/02_shared-drizzle-workspace-package.md](./learnings/examples/02_shared-drizzle-workspace-package.md)
+
+### Prompts
+
+- [03_repo-hc-install-bootstrap.md](./prompts/03_repo-hc-install-bootstrap.md)
+- [examples/01_workspace-peer-dependency-resolution.md](./prompts/examples/01_workspace-peer-dependency-resolution.md)
+- [examples/02_shared-drizzle-workspace-package.md](./prompts/examples/02_shared-drizzle-workspace-package.md)
+
+### Rules
+
+- [01_mask_sensitive-data.md](./rules/01_mask_sensitive-data.md)
+- [02_write-in-english.md](./rules/02_write-in-english.md)
+- [03_keep-readme-updated.md](./rules/03_keep-readme-updated.md)
+- [04_use-dedicated-branch-for-large-features.md](./rules/04_use-dedicated-branch-for-large-features.md)
+- [05_update-mermaid-on-architecture-changes.md](./rules/05_update-mermaid-on-architecture-changes.md)
+- [06_require-comprehensive-feature-docs.md](./rules/06_require-comprehensive-feature-docs.md)
+- [07_require-feature-plan-and-env-docs.md](./rules/07_require-feature-plan-and-env-docs.md)
+- [08_agents-override-prefer-reusable-modules.md](./rules/08_agents-override-prefer-reusable-modules.md)
+
+### Skills
+
+- No repository-local skills currently.
+
+## Notes
+
+- `examples/` files are historical references and may describe earlier repository phases.
+- New project-direction learnings should be added outside `examples/`.

package/.agents/learnings/03_repo-hc-install-bootstrap.md

@@ -0,0 +1,41 @@
+# Learning: repo-hc Install Bootstrap to Project Root
+
+## Links
+- README: `../README.md`
+- Prompt: `../prompts/03_repo-hc-install-bootstrap.md`
+- Plan: `../plans/2026-03-11-publishable-repo-hc-package-bootstrap.md`
+
+## Context
+The package needed to support one-step installation with:
+
+```bash
+pnpm add repo-hc
+```
+
+while ensuring these assets appear in consumer project roots:
+
+- `.agents/`
+- `docs/`
+- `AGENTS.md` (canonical)
+- `AGENT.md` (compatibility alias)
+
+## Decision
+- Use `postinstall` to run an internal bootstrap command (`repo-hc install`).
+- Implement a non-destructive copy strategy:
+  - copy missing files/directories
+  - preserve existing files by default
+  - allow explicit overwrite via `repo-hc init --force`
+
+## Implementation Structure
+- `bin/repo-hc.cjs`: CLI command dispatch (`init`, `install`)
+- `lib/bootstrap.cjs`: reusable recursive copy logic
+- `package.json`: `bin`, `files`, `postinstall`, and test script
+
+## Guardrails
+- `install` never breaks package installation if bootstrap fails.
+- `REPO_HC_SKIP_POSTINSTALL=1` allows skipping bootstrap in CI or controlled setups.
+- Global installs are ignored by bootstrap to avoid writing outside intended project roots.
+
+## Validation
+- Added `node:test` coverage for copy and force-overwrite behavior.
+- Updated docs to describe install behavior and manual re-run commands.

package/.agents/learnings/examples/01_workspace-peer-dependency-resolution.md

@@ -0,0 +1,20 @@
+# Workspace Peer-Dependency Resolution: Example Learning
+
+## Links
+- README: `../../README.md`
+- Prompt: `../../prompts/examples/01_workspace-peer-dependency-resolution.md`
+
+## Context
+During dependency installation in a multi-module workspace, peer dependency warnings appeared for transitive packages.
+
+## Root Cause
+An indirect dependency introduced stricter peer requirements that were not satisfied by the currently resolved versions.
+
+## Proven Fix
+Add explicitly compatible versions in affected modules and run dependency installation again so the lockfile is updated.
+
+## Result
+Peer dependency warnings disappear after installation.
+
+## Setup Note For Later
+When dependencies move between beta/alpha channels, verify peer requirements first and pin compatible versions where needed.

package/.agents/learnings/examples/02_shared-drizzle-workspace-package.md

@@ -0,0 +1,33 @@
+# Shared Drizzle Workspace Package: Implementation Learnings
+
+## Links
+- README: `../../README.md`
+- Prompt: `../../prompts/examples/02_shared-drizzle-workspace-package.md`
+
+## Context
+A new large feature introduced a shared Drizzle package under `packages/db` for reuse across apps.
+
+## Decisions
+- Created `@workspace/db` as the canonical package for shared DB concerns.
+- Kept responsibilities modular (`schema`, `types`, `config`, `adapters`, `migrations`, `seeds`).
+- Exposed stable subpath exports instead of a single barrel.
+- Implemented runtime-specific adapter factories:
+  - `@workspace/db/adapters/node-postgres`
+  - `@workspace/db/adapters/libsql`
+- Added explicit connection validation helpers with sanitized error messages.
+- Kept env reads out of schema and adapter modules.
+
+## Test And Validation Pattern
+- Add unit tests for adapter config validation, especially invalid input paths.
+- Run package-local checks first:
+  - run package-local `typecheck`
+  - run package-local `test`
+- Then run workspace-wide checks.
+
+## Documentation Pattern
+When a cross-cutting package is added, update both:
+- root docs (`README.md`, `CONTRIBUTING.md`)
+- `.agents/README.md` index (if `.agents` files changed)
+
+## Branching Rule Reminder
+This scope is a large feature and must be implemented on a dedicated feature branch, not `main`.

package/.agents/plans/2026-03-11-github-housekeeping-doc-refresh.md

@@ -0,0 +1,26 @@
+# Plan: GitHub Housekeeping Package Documentation Refresh
+
+## Date
+- 2026-03-11
+
+## Goal
+Align repository documentation with the current project direction: a future npm package for automated GitHub housekeeping guided by an AI agent (initially optimized for OpenAI Codex).
+
+## Scope
+1. Update `AGENTS.md` to remove stack-specific assumptions that are unrelated to agent behavior rules.
+2. Replace root `README.md` with a package-focused project overview.
+3. Refresh docs under `docs/` so links and narrative match the current repository.
+4. Sync supporting docs (`CONTRIBUTING.md`, `SECURITY.md`, `.agents/README.md`, and affected `.agents/rules/*`) where stale references exist.
+
+## Non-Goals
+- Implementing runtime package code.
+- Publishing to npm in this change.
+
+## Deliverables
+- Updated guidance for AI-assisted repository housekeeping workflows.
+- New root README with centered shields and actionable onboarding.
+- Cleaned documentation graph with valid links and consistent terminology.
+
+## Validation
+- Manual link and terminology consistency pass across edited docs.
+- `git diff --name-only` review to ensure changes stay documentation-focused.

package/.agents/plans/2026-03-11-publishable-repo-hc-package-bootstrap.md

@@ -0,0 +1,28 @@
+# Plan: Publishable repo-hc Package Bootstrap
+
+## Date
+- 2026-03-11
+
+## Goal
+Enable consumers to run `pnpm add repo-hc` (without `-D`) and receive the following assets in their project root:
+- `.agents/`
+- `docs/`
+- `AGENTS.md` (canonical)
+- `AGENT.md` (compatibility alias)
+
+## Scope
+1. Add a publishable npm package scaffold (`package.json`, CLI entrypoint, install hook).
+2. Implement non-destructive root bootstrap logic for copying package assets into `INIT_CWD`.
+3. Provide a manual command (`repo-hc init`) for re-running bootstrap.
+4. Add tests for bootstrap copy behavior.
+5. Update documentation to reflect installation and bootstrap behavior.
+
+## Non-Goals
+- Implementing full AI workflow runtime logic.
+- Publishing to npm in this change.
+
+## Validation
+- Run tests for copy behavior.
+- Dry-run local CLI init into a temporary folder.
+- Verify docs mention `pnpm add repo-hc` and expected copied assets.
+

package/.agents/plans/examples/2026-03-11-add-docs-workflow-guides.md

@@ -0,0 +1,31 @@
+# Plan: Add Self-Contained Docs and Feature-Branch Workflow Guides
+
+## Scope
+Create comprehensive user and developer documentation under `docs/` that explains:
+
+- how the self-contained docs system works
+- how the feature-branch + scoped-plan workflow works
+- how this keeps repo history and PRs clean for community collaboration
+- which concrete benefits users receive from this workflow quality model
+
+## Steps
+1. Add a new feature docs area `docs/workflow/` with:
+   - `README.md`
+   - `developers.md`
+   - `users.md`
+2. Add Mermaid docs under `docs/mermaid/` for:
+   - docs-system structure and update flow
+   - community contribution and PR lifecycle
+3. Cross-link all related docs in both directions:
+   - `docs/README.md` -> new workflow docs + Mermaid files
+   - `docs/workflow/README.md` -> users/developers + Mermaid files
+   - Mermaid docs -> docs home + workflow docs
+4. Update `docs/project/README.md` and root `README.md` so the new workflow docs are discoverable from existing entry points.
+5. Add a concise `.agents` learning + prompt entry if reusable process guidance emerges.
+
+## Security Considerations
+- Keep the workflow docs explicit about server-side authz and secret handling responsibilities.
+- Reinforce documentation-as-contract to reduce unsafe or undocumented changes.
+
+## Environment Variables
+No new environment variables are introduced by this documentation change.

package/.agents/plans/examples/2026-03-11-central-api-docs-mermaid.md

@@ -0,0 +1,23 @@
+# Plan: Central API Architecture Docs Update
+
+## Goal
+Update `/docs` architecture diagrams to show:
+- `apps/api` as the central backend boundary
+- `apps/admc` and `apps/frontend` connect to `apps/api`
+- only `apps/api` connects to the database
+
+## Scope
+- `docs/mermaid/admc-architecture.md`
+- `docs/mermaid/api-architecture.md`
+- `docs/mermaid/db-architecture.md`
+- new central architecture Mermaid file under `docs/mermaid/`
+- index/link updates in docs files that list Mermaid diagrams
+
+## Steps
+1. Add a new system-level Mermaid diagram showing runtime boundaries and allowed data flow.
+2. Update existing architecture Mermaid docs so they all match the same boundary model.
+3. Update docs indexes (`docs/README.md` and feature README files where relevant) to include the new diagram links.
+4. Verify links and Mermaid syntax consistency.
+
+## Security Intent
+Keep architecture docs explicit that DB access is server-side only through `apps/api`, with no direct DB path from clients (`apps/frontend` / `apps/admc`).

package/.agents/prompts/03_repo-hc-install-bootstrap.md

@@ -0,0 +1,17 @@
+# Prompt: repo-hc One-Step Install Bootstrap
+
+## Links
+- README: `../README.md`
+- Learning: `../learnings/03_repo-hc-install-bootstrap.md`
+- Plan: `../plans/2026-03-11-publishable-repo-hc-package-bootstrap.md`
+
+## Original Prompt (Sanitized)
+```text
+What is required so users can run "pnpm add repo-hc" and automatically receive:
+- .agents
+- docs
+- AGENTS.md (canonical)
+- AGENT.md (compatibility alias)
+
+Implement it without using -D.
+```

package/.agents/prompts/examples/01_workspace-peer-dependency-resolution.md

@@ -0,0 +1,10 @@
+# Prompt: Workspace Peer-Dependency Resolution
+
+## Links
+- README: `../../README.md`
+- Learning: `../../learnings/examples/01_workspace-peer-dependency-resolution.md`
+
+## Original Prompt
+```text
+Fix peer dependency warnings in this workspace install.
+```

package/.agents/prompts/examples/02_shared-drizzle-workspace-package.md

@@ -0,0 +1,10 @@
+# Prompt: Shared Drizzle Workspace Package
+
+## Links
+- README: `../../README.md`
+- Learning: `../../learnings/examples/02_shared-drizzle-workspace-package.md`
+
+## Original Prompt
+```text
+Please implement the drizzle plan (large feature)
+```

package/.agents/rules/01_mask_sensitive-data.md

@@ -0,0 +1,39 @@
+# Rule: Always Mask Sensitive Data
+
+## Links
+- README: `../README.md`
+- Related Rule: `./02_write-in-english.md`
+- Related Rule: `./03_keep-readme-updated.md`
+
+## Scope
+This rule applies to the creation and maintenance of:
+
+- Learnings
+- Prompts
+- Docs
+- Notes and internal agent files
+
+## Requirement
+Sensitive data must always be masked or removed.
+No real secrets may appear in files or examples.
+
+## Never Store Unmasked
+- API Keys
+- Access Tokens / Refresh Tokens
+- Passwords
+- Private Keys / Certificate Contents
+- Session-Cookies
+- Webhook Secrets
+- Connection strings with credentials
+- Personal or confidential operational data
+
+## Allowed Representation
+Use placeholders only, for example:
+
+- `<API_KEY_REDACTED>`
+- `<TOKEN_REDACTED>`
+- `<PASSWORD_REDACTED>`
+- `<SECRET_REDACTED>`
+
+## Decision Rule
+If it is unclear whether a value is sensitive, treat it as sensitive and mask it.

package/.agents/rules/02_write-in-english.md

@@ -0,0 +1,23 @@
+# Rule: Write All Text in English
+
+## Links
+- README: `../README.md`
+- Related Rule: `./01_mask_sensitive-data.md`
+- Related Rule: `./03_keep-readme-updated.md`
+
+## Scope
+This rule applies to all written project content, including:
+
+- Learnings
+- Prompts
+- Documentation
+- Notes and internal agent files
+
+## Requirement
+All text must be written in English.
+
+## Exceptions
+Use another language only if explicitly requested by the user for that specific content.
+
+## Consistency
+Headings, labels, examples, and inline comments in docs must also be in English.

package/.agents/rules/03_keep-readme-updated.md

@@ -0,0 +1,20 @@
+# Rule: Keep README Updated
+
+## Links
+- README: `../README.md`
+- Related Rule: `./01_mask_sensitive-data.md`
+- Related Rule: `./02_write-in-english.md`
+
+## Scope
+This rule applies to all changes under `.agents`.
+
+## Requirement
+Whenever files are added, removed, renamed, or their purpose changes in `.agents`, update `.agents/README.md` in the same change.
+
+## Minimum README Update
+- Keep the index current (learnings, prompts, rules).
+- Keep usage instructions aligned with the current workflow.
+- Keep cross-links valid.
+
+## Enforcement
+A docs change is incomplete if `README.md` is outdated.

package/.agents/rules/04_use-dedicated-branch-for-large-features.md

@@ -0,0 +1,25 @@
+# Rule: Use a Dedicated Git Branch for Large Features
+
+## Links
+- README: `../README.md`
+- Related Rule: `./03_keep-readme-updated.md`
+
+## Scope
+This rule applies to all new large feature work.
+
+## Requirement
+For every new large feature, create and use a dedicated git branch.
+Do not implement large features directly on `main`.
+
+## What Counts as a Large Feature
+Treat work as a large feature if one or more of the following is true:
+
+- It affects multiple modules, docs sections, or workflows.
+- It introduces new architecture, major workflows, or cross-cutting behavior.
+- It requires multiple commits over more than one working session.
+- It has elevated risk, migration impact, or broad testing surface.
+
+## Branch Guidance
+- Use clear branch names, for example: `feat/<topic>` or `feature/<topic>`.
+- Keep branch scope focused to one feature.
+- Open a PR for review before merge.

package/.agents/rules/05_update-mermaid-on-architecture-changes.md

@@ -0,0 +1,26 @@
+# Rule: Update Mermaid Diagrams on Architecture Changes
+
+## Links
+- README: `../README.md`
+- Related Rule: `./03_keep-readme-updated.md`
+- Related Rule: `./04_use-dedicated-branch-for-large-features.md`
+- Related Rule: `./06_require-comprehensive-feature-docs.md`
+
+## Scope
+This rule applies whenever architecture is added, changed, or removed.
+
+## Requirement
+When architecture changes, update documentation in the same change and include updated Mermaid diagrams that reflect the new architecture.
+
+## Documentation Targets
+- Prefer files under `docs/mermaid/` for architecture and workflow diagrams.
+- Keep related references in `AGENTS.md` and `.agents` aligned when architecture guidance changes.
+
+## Minimum Update
+- Add or update at least one Mermaid diagram for the changed architecture.
+- Ensure diagram nodes, boundaries, and data flow match the implementation.
+- Ensure Mermaid syntax renders on GitHub (quote labels with special characters where needed).
+- Remove or replace stale Mermaid diagrams that no longer reflect reality.
+
+## Enforcement
+Architecture changes are incomplete if Mermaid architecture docs are missing or outdated.

package/.agents/rules/06_require-comprehensive-feature-docs.md

@@ -0,0 +1,73 @@
+# Rule: Require Comprehensive Feature Documentation
+
+## Links
+- README: `../README.md`
+- Related Rule: `./03_keep-readme-updated.md`
+- Related Rule: `./05_update-mermaid-on-architecture-changes.md`
+
+## Scope
+This rule applies to every feature that changes one or more of the following:
+
+- architecture
+- setup or runtime configuration
+- developer workflow
+- user-facing behavior
+- shared contracts or interfaces
+
+## Requirement
+For in-scope feature work, documentation is part of the implementation and must be added or updated in the same change.
+
+## Mandatory Documentation Structure
+For each affected feature area `<feature>`:
+
+1. Add or update `docs/<feature>/developers.md`.
+2. Add or update `docs/<feature>/users.md`.
+3. Add or update `docs/<feature>/README.md` as a local index.
+4. Add or update Mermaid diagrams in `docs/mermaid/` (at minimum architecture or workflow).
+5. Add or update global index links in `docs/README.md`.
+
+## Content Expectations
+
+### Developer Documentation (`developers.md`)
+Must cover:
+
+- architecture intent and boundaries
+- setup and environment requirements
+- validation and test workflow
+- extension/change workflow
+- security notes
+- troubleshooting for common failures
+
+### User Documentation (`users.md`)
+Must cover:
+
+- quick start and primary usage flows
+- stable API/usage surface
+- safe integration examples
+- limitations and constraints
+- FAQ or operational notes where relevant
+
+### Mermaid Documentation
+Must cover:
+
+- system architecture or data flow
+- at least one runtime or change workflow
+- GitHub-compatible Mermaid syntax (quote labels when using special characters)
+
+## Linking Requirements
+Cross-link all relevant docs in both directions:
+
+- `docs/README.md` -> feature docs + Mermaid docs
+- `docs/<feature>/README.md` -> developers/users + Mermaid docs
+- each Mermaid file -> docs home + related feature docs
+
+## Definition of Done
+A feature is not done until:
+
+- implementation and docs are merged together
+- docs link graph is complete and non-stale
+- Mermaid diagrams match the current implementation
+- no duplicated or contradictory setup/usage instructions remain
+
+## Enforcement
+PRs that change in-scope behavior without the required docs updates should be treated as incomplete.

package/.agents/rules/07_require-feature-plan-and-env-docs.md

@@ -0,0 +1,39 @@
+# Rule: Require Feature Plans and Environment Variable Documentation
+
+## Links
+- README: `../README.md`
+- Related Rule: `./04_use-dedicated-branch-for-large-features.md`
+- Related Rule: `./06_require-comprehensive-feature-docs.md`
+
+## Scope
+This rule applies to all feature work, regardless of feature size.
+
+## Requirement
+Every feature must include:
+
+1. A dedicated feature branch.
+2. A scoped implementation plan before coding.
+3. Documentation updates for any new environment variables.
+
+## Branch Requirement
+- Do not implement feature work directly on `main`.
+- Use clear branch naming such as `feat/<topic>` or `feature/<topic>`.
+
+## Plan Requirement
+- Create or update a plan before implementation starts.
+- Prefer storing plans under `.agents/plans/`.
+- Keep the plan focused, actionable, and aligned with final implementation.
+
+## Environment Variable Documentation Requirement
+When introducing or changing environment variables:
+
+- Add the variable to `.env.example` in the same change.
+- Document it in relevant developer docs (at minimum in `docs/<feature>/developers.md` or equivalent).
+- Include:
+  - purpose
+  - server-only vs public exposure scope
+  - expected format/example placeholder
+  - default/fallback behavior (if any)
+
+## Enforcement
+Feature work is incomplete if branch + plan + env-doc requirements are not satisfied.

package/.agents/rules/08_agents-override-prefer-reusable-modules.md

@@ -0,0 +1,26 @@
+# AGENTS Override: Prefer Reusable Internal Modules
+
+## Links
+- README: `../README.md`
+- Related Rule: `./03_keep-readme-updated.md`
+
+## Override Policy
+Whenever useful, prefer reusable internal modules over one-off implementation blocks.
+
+## Applies To
+- policy definitions
+- orchestration helpers
+- GitHub adapter logic
+- shared utilities and domain helpers
+- shared type contracts
+
+## Decision Heuristic
+Prefer extracting a reusable module when at least one condition is true:
+
+- logic is likely to be reused by multiple workflows
+- logic encodes shared domain behavior
+- logic is expected to grow and needs isolated tests
+- keeping it inline would duplicate patterns
+
+## Exception
+Keep implementation local when it is clearly one-off and unlikely to be reused.